Keeping code undocumented now might save you a few minutes, but it will undoubtedly cause you pain and misery when you do revisions 6 months from now.

As you surely know, Matlab’s built-in help function parses comments immediately following the function byline and outputs these comments in the command window. It has a couple of bells and whistles. If you write a line of help text starting with “See Also”, it will link the subsequent function names to their help. It’s also possible to create links that execute Matlab code. You can use this feature to link to a website (using the web command) or to another function’s help (with the help command). Here’s an example:

function [] = myfun()
%function [] = myfun()
%<a href="matlab:disp('Hello world');">Click here</a>
%See also fprintf
end

with the output:

Packages of functions

That’s pretty much all there is to it for single functions. The more interesting aspects of Matlab’s help come when you work with classes and packages of functions. If you type help foldername, where foldername is the name of a folder in Matlab’s path, you will see each .m file in the folder listed with the first line of help in each file. It’s possible to customize the display information by creating a file called Contents.m in the relevant folder. Contents.m should contain comments with the names of functions on the left hand side and descriptions of the functions on the right hand side. These two parts should be separated by a dash (-), like so:

%Contents of fastBSpline:
%
%fastBSpline     - Construct fastBspline object
%TryBSpline      - Examples of using fastBSpline
%CompileMexFiles - Compiles Mex files needed by fastBSpline

Which gives this output:

It’s possible to maintain this information manually, or to modify it using the Contents File Report feature which is located in the Actions dropdown (gear icon) in the Current Folder window:

This menu also contains the Help Report option, which allows you to browse the help that you’ve written for all the files in the current folder. In addition, the Dependency Report will show you functions which are called by files inside the current folder, which is useful when you’re about to share functions and you want to make sure that you’ve included all the required files.

It’s possible to write help for packages that will show in the Help browser. This is a more involved process, which is outlined on The Mathworks’ website.

Classes

I’ve discussed object-oriented programming in Matlab before and mentioned that there’s a mechanism to generate complex documentation for classes, not unlike Javadoc. It works like this. When you define classes, write help as usual underneath the classdef keyword . Immediately following this, you write a comment of the form “<classname> properties:”, where <classname> is the name of your class, followed by a list of properties on the left-side, a dash, and descriptions on the right hand-side. It’s essentially the same format as Contents.m.

The parser is a little dumb. The name of the class in the help must match the name of your class defined in classdef (it can include the package name or not before the actual name, however). There must be at least one space between the dash (-) and the right hand side description. You can use the same mechanism with “<classname> Methods:” to include short descriptions of class methods.

Matlab will link to the help of the appropriate property of method. Be careful, however: Matlab will extract help from the comments below a method’s declaration but from those above a property’s declaration. Now if you’ve done this, correctly, you should have nice, linked documentation for classes, like this:

Now if you type doc className rather than help className, you will see a more complete description of the class including all the information Matlab can gather from the comments:

Using external tools

Finally, there exist tools to create external documentation from .m files, especially useful in larger projects. This Doxygen plugin will helpfully create dependency graphs for classes in addition to browsable documentation. m2html is another popular choice.