Function Header Comments - GCMLab/GCMLab-FEM GitHub Wiki
Function header comments should describe:
- What the function does
- What parameters are required
- What values the function returns
It is worth mentioning any default values for parameters, which parameters are optional, and any variants in the output.
For this repository, Matlab-style headers are used. This formatting style is recognized by the help function in Matlab.
The first line contains the function name (in all-caps) and a brief description of the function. Anytime the function name is used in all-caps, Matlab automatically fixes the case and bolds it in the documentation from the help command.
Below that, the function usage is specified with each output defined in a separate paragraph. The output type and size should be specified.
The usage for optional input may also be defined on a separate line.
All parameters that are input to the function must be specified, along with their data type and size. Oftentimes, structure arrays containing multiple fields are passed to a function. The specific fields used in the function should be documented in the header comments.
In many cases, it is also beneficial to add references that can be referred to throughout the function.
The documentation can be obtained at any time using the help function in Matlab.
