mtoc++ - Doxygen filter for Matlab and tools

Create nice documentation for your MatLab project using doxygen

Description

This somewhat larger project allows to create comprehensive documentation for MatLab files and classes (including packages) using a doxygen filter named mtoc++.
Moreover, a tool/class named MatlabDocMaker allows to create the documentation from within MatLab.
For Windows and Unix!

Rough feature list:
- Supports classes and packages
- Also @folders for classes
- Abstract & Static methods
- Special tags "@type" and "@default" for method parameters and return values for more expressive documentation
- Automatic detection of used fields and appropriate documentation
- Default documentation for methods, parameters, return values etc
- detection of getter & setter methods
- included latex support and shortcuts for higher readability in plain text (e.g. `\sqrt{x}` is like @f$\sqrt{x}@f$)
- support for MatLab events
- much more...

The complete documentation can be found at http://www.morepas.org/software/mtocpp/docs/index.html, but is also included in the download. Detailed instructions for installation and configuration can be found therein, however, here are the basic steps needed to get started:

# Installation
# Unix:
- download & unzip in a folder.
- Create a build folder inside and change to that dir
- Run "cmake .." and "make"
- then "mtocpp" and "mtocpp_post" are inside the folder, the documentation in "/docs"
# Windows:
As we cannot provide the binaries through the FileExchange platform, please go to the download page http://www.morepas.org/software/mtocpp/docs/download.html and obtain them from there.

# Setup the DocMaker
- Place the MatlabDocMaker.m in your project's MatLab path
- Copy the contents of the <mtoc++-source-dir>/tools/config folder into e.g. a subfolder of your MatLab project
- place binaries (win or unix) on PATH environment or inside the folder created in the last step
- Call the MatlabDocMaker.setup method and use the folder from the previous steps as your "documentation configuration files directory".
- Use the MatlabDocMaker.create method to create your documentation!

We welcome any improvement suggestions and critics.

• Required Products: MATLAB
• MATLAB release: MATLAB 7.9 (2009b)
• Other requirements: use: doxygen, m4; compilation: ragel, cmake

[Evgeny Pr]

Great! This tool is convenient and works better than http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab

Now I'll use the mtoc++! Thanks!

[Evgeny Pr]

One question:

In defenition properties of class require write ";" in end of line:

properties
    % Some property of class
    Preperty;
end

If not write ";", the class is not processed. For example:

properties
    % Some property of class
    Preperty
end

Could you fix this bug?

[Evgeny Pr]

And second question:

As documenting functions and classes that are outside of the packages directories?

MyProjectDir
  +-- +Package
           PackageFunction.m
           PackageClass.m
  +-- SomeDir
           SomeFunction.m
           SomeClass.m

[Evgeny Pr]

Ok, now the second question isn't actual.
(Set SHOW_FILES = YES in Doxyfile) :)

[Wess]

Would anyone happen to know how I can extract documentation from standard (static) m files i.e. not a class...not a function etc... ? Also, how do I configure the HTML tree to include a new section such as "Files" displaying a tree of all m files? This really a great tool. I am eager to learn it. Thank you!

[Daniel Wirtz]

Hey Wess,
Your second question has actually been answered by Evgeny Pr just above; Doxygen has a flag "SHOW_FILES" which creates a file list for you.
Regarding documentation from scripts, we will consider to let mtoc++ automatically generate a function signature to mimic a function with no in and outputs.

[Wess]

Thank you. Yes, I tried the SHOW_FILES a few days ago but it did not work for me thus I thought that was not the correct answer. Perhaps I asked the wrong question :) Are there other flags that need to be set? I do have recursive enabled to include subdirectories in the root source. The feature for mimicking function from scripts would be outstanding. Thanks again for all the help and for a great package.

[Martin]

Hi Wess,

the documentation functionality for scripts is already implemented. Just make sure, that the first line of your script is a comment, and this comment block will be interpreted as documentation for a function named like your script.

Concerning your problems with the "Files" Section, SHOW_FILES should be the right option. If your functions are not documented yet, you might also want to activate the EXTRACT_ALL flag, because otherwise Doxygen might not produce documentation for your undocumented functions.

[Wess]

Thanks Daniel! Thanks Martin! Everything works now. For once in my life I am actually going to enjoy documenting my work moving forward. What a great tool!

[Wess]

This tool is an excellent compliment to doxygen and I can only imagine that its going to get even better with time. Right out of the box I was able to get the tool integrated with a project and generate some very professional looking documentation.

[Catalin Lupu]

It is really a great tool for me also but I have a small problem. One of my classes is making use of the following construct:

properties (SetAccess = private, SetObservable, AbortSet)
% here properties
end

When I try to generate the help files first docxygen fails and doesn't give any explanation why. Then the process continues and finally I am told in the Matlab command line that the parser failed where the word 'AbortSet' is.

I had similar errors with other Matlab constructs and updating to the code I was able to eliminate them one by one. I got stuck with the one mentioned above.

Do you have any hints of how I could eliminate this problem without making huge changes to my existing source codes?

Thank you for this great class and tool. Impressive!

With respect, Catalin

[Catalin Lupu]

 

[Daniel Rohrbach]

Great Job. This is really a useful tool and it is exactly what I was looking for. Thanks a lot!
 
Just 2 small issues (bugs) (Matlab R2011a):
1.: if I have a function within a class which has the following form:

function test
switch
…
end
end
then

I got an parser error. The problem is that the switch command must be indented:

function test
    switch
    …
    end
end

then it works.

2.: this issue does not affect everyone. I modified some of my code using other editors. For some reasons I got ‘\n’ replaced for line break by ‘\r\n’ which causes an parse error. I replaced in all my m-files single ‘\n’ by ‘\r\n’ and now it works.

Hopefully this was usefull.

[Daniel Wirtz]

Dear Catalin,

could you provide us with more of those "Matlab constructs" that caused mtoc++ not to work properly? This might help to further improve our program!
thanks,
Dan

[Daniel Wirtz]

Dear Folks,
i've just updated the windows binaries for the current development version 1.3 on http://www.morepas.org/software/mtocpp/docs/download.html.

enjoy!

[Roland Michaely]

Dear all
I installed and tested successfully mtoc++1.3 under windows (binary generation included) with the help of Daniel.
Thanks a lot, great work!

We will use mtoc++ and doxygen for our Matlab documentation!

[Jesse Hopkins]

Think I got it figured out. Was missing MSVCP100.dll. I installed Microsoft Visual C++ 2010 SP1 Redistributable from here: http://www.microsoft.com/download/en/confirmation.aspx?id=8328

I found an interesting thread on the topic of static vs dynamic linking of these libraries here: http://social.msdn.microsoft.com/Forums/en-US/Vsexpressvc/thread/3a007184-80e9-4e25-b5ad-ff31b028c051

Everything went pretty smooth, got some good looking documentation. I did however, manage to get a Grrr! message :). Here's the output:

MTOCPP:C:/HopkinsSynergySandbox/CSI/CSI_CORE/0.0/jhopkin/CsiPlottingTool/@AmsPlotManager/AmsPlotManager.m: PARSE ERROR in line 27
Message: Grrrr!!!!
Next 20 characters to parse:
% Matlab class for c

[gg]

Daniel,

several classes of mine produce errors when parsing. Following below I include one log-file and following that a simple example.

Regards,
gg
--------------snip!-------------------
MTOCPP:C:/Users/fango/tmp/test/errorClass.m: PARSE ERROR in line 20
Message: Grrrr!!!!
Next 20 characters to parse:
0;

end

end

end
---------------snip!------------------
classdef errorClass

properties

end

methods

function ob = errorClass

end

function po = innocent_method

if 1
end
po=0;

end

end

end
---------------snip!------------------

[Daniel Wirtz]

Hey gg,
well i'd also complain to parse that code :-)
fun aside, the reason for the error is simply the missing matlab indentation. our parser relies on the files to have that, as the original matlab parser mlint is of course not available to us and we need some means to know where we are and what .c to produce of that.

when i take your above example and run matlab's builtin indentation on it, the error disappears. you might find this post "http://www.mathworks.com/matlabcentral/answers/11457-how-to-apply-smart-indent-to-a-file-programmatically" interesting.

however, as we frequently find people coming up with the same errors we might include some more explicit hints toward this issue into the documentation.

[Justin]

Hi Daniel,
Do you have any suggestions on how to handle varagin? I use inputParser to validate optional parameters of the type ('ParamName', paramValue) in my constructors and other functions.

 Is it possible to have the type show under the 'Parameters:' heading instead of only in the function definition line of the doxygen output?

[Daniel Wirtz]

Hey Justin,
the way we handle varargin is to define a type called that way, so that doxygen automatically creates a link to that whenever it occurs somewhere. as it turns out, it will be linked in a classes functions summary (at the parameter list), but then of course not in the detailed function description as long as it is not explicitly included there.
here's my suggestion for the current version: in the "Parameters:" section, declare varargin as a single parameter and add a description what should be contained in there. (if you also add the "@type varargin" tag behind, will get double varargin in the fcn signature list but a type in the detailed description).
we haven't fully decided what to do best about the whole varargin thing, as the ways to use it (i.e. inputParser etc) are way too numerous.
however, we will think about an easy way to also include varargin-parsing into mtoc++, maybe something like a "Varargin:" section with "<name>: <desc> @type <type> @default <default>".
you are more than welcome to share your thoughts on that with us!
regards,
Daniel