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 realize the question is stale, but for the benefit of Google: Matlab has a built-in feature for that. You write your comments in a certain style (a la JavaDoc) and they get picked up by the help and doc functions. It can be used to document classes, properties, and methods. It is surprisingly complete, yet a little finicky. The doc is here:

http://www.mathworks.com/help/matlab/creating-help.html

Answer 2

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 3

Try Sphinx with the matlabdomain extension. Sphinx is a Python package that auto-documents code using ReStructuredText (rst) markup. The extension sphinxcontrib-matlabdomain allows auto-documentation of MATLAB code that uses rst markup recognized by Sphinx in its docstrings. Send bugs and suggestions to the issue tracker on BitBucket.

For example, the following code in my_project/my_fun.m:

function [outputs] = my_fun(args)
% MY_FUN does really cool stuff
% [OUTPUTS] = MY_FUN(ARGS)
%
% :param args: Input arguments
% :type args: cell array
% :returns: outputs
% :raises: :exc:`my_project.InvalidInput`

code ...
end

would be documented in an rst file like this:

.. _my-project

My Project
==========
.. automodule:: my_project

    This folder contains all the functions and classes for my project.

My Function
-----------
.. autofunction:: my_fun

and would produce html (or pdf, latex, and many others) like what is shown on this blog post.

Answer 4

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