5.3: Function Documentation
- Page ID
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:
The signature of the function, which includes the name of the function, the input variable(s), and the output variable(s).
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.
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.
Any preconditions and postconditions.