5.3: Function Documentation

At the beginning of every function file, you should include a comment that explains what the function does:

% res = myfunc(x)
% Compute the Manhattan distance from the origin to the
% point on the unit circle with angle (x) in radians.

function res = myfunc(x)
% this is not part of documentation given by help function

    s = sin(x);
    c = cos(x);
    res = abs(s) + abs(c);
end

When you ask for help, MATLAB prints the comment you provide.

>> help myfunc
  res = myfunc(x)
  Compute the Manhattan distance from the origin to the
  point on the unit circle with angle (x) in radians.

There are lots of conventions about what should be included in these comments. Among other things, it’s a good idea to include the following:

Signature

The signature of the function, which includes the name of the function, the input variable(s), and the output variable(s).

Description

A clear, concise, abstract description of what the function does. An abstract description is one that leaves out the details of how the function works and includes only information that someone using the function needs to know. You can put additional comments inside the function that explain the details.

Variables

An explanation of what the input variables mean; for example, in this case it is important to note that x is considered to be an angle in radians.

Conditions

Any preconditions and postconditions.