How to document object-oriented MATLAB code?

Question

I'm writing a sizable application using object-oriented MATLAB, and this has gotten me thinking about how to document the code. If this was C, I would use Doxygen. For Java, I'd use JavaDoc. Both have mostly agreed-upon standards for how class and method documentation should look and what it should contain.

But what about MATLAB code? The most I've seen in TMW's own classes is a short sentence or two at the top of the class, and I can't find any topics devoted to documenting sizable MATLAB applications.

So how do you document your MATLAB classes? Any particular style issues or additional tools?

Answer 1

I document my oo code the following way:

1. At the beginning of the file that contains 'classdef', I write a summary of what the class does, and typical usage. I also explain properties in detail and I add a 1-sentence description of each method.
2. After each property definition, I add one explanatory sentence about it (on the same line)
3. Each method is documented like a function, i.e. it has a H1-line, a synopsis, and an explanation of the input and output parameters.

When you call 'doc myClass', you will see (1) at the beginning, followed by the list of properties explained by the sentences you added in (2) and the list of methods that show the H1-line and the rest of the help (3) if you click on the link.

In addition, all my classes subclass a general superclass which implements (among others) the method 'help' that calls doc(class(obj)), which allows me to bring up the help from every instance of the class.

Example

%# MYCLASS is a sample class
%# All this text will show up at the top of the help if you call 'doc myClassName'
%#
%# myClass is an example for documentation. It implements the following properties and methods:
%# PROPERTIES
%#    myProp - empty sample property (some more explanation could follow here)
%#
%# METHODS
%#    myMethod - sample method that calls doc
%#

classdef myClass

properties
    myProp = []; %# empty sample property
end %# properties

methods

%%# MYMETHOD -- use %% so that you can easily navigate your class file
function myMethod(obj)
%#MYMETHOD calls up the help for the object
%#
%# SYNOPSIS myMethod(obj)
%# INPUT obj: the object
%# OUTPUT none
%#
   try
      doc(class(obj))
   catch
      help(class(obj))
   end
   end %#myMethod
end %#methods

end %#myClass

Edit 1 If you want a nice html documentation, you can, in addition, use m2html to generate it for you. M2html will collect the help texts and it can even do dependency graphs.

Edit 2 While m2html documents standard Matlab code nicely, it has no specific support for classes. This means that you get the methods as 'subfunctions' linked in the class, but you do not get as nice a summary as you'd get with Doxygen, or which you get with the built-in documentation browser.

Answer 2

There exists a Doxygen-Adapter for M-Files on FileExchange, see http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab.