Make Doxygen output more Matlab-esque

[benjamin-heasly]

The current oom2cpp converter (in the RenderToolbox3 gh-pages branch) is OK for fitering Matlab code into something Doxygen can parse. But the results look unfamiliar to some Matlab users.

There are other Matlab converters that work with Doxygen, and produce results that are more Matlabish. What features do we want to crib, to improve oom2cpp?

[benjamin-heasly]

Nicolas Cottaris has some pointers to other tools:

I have found two different tools on Matlab's file exchange:
(1) http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab
(2) http://www.mathworks.com/matlabcentral/fileexchange/33826-mtoc++-doxygen-filter-for-matlab-and-tools
I have examined extensively the first one. It produces decent documentation, but I am not thrilled with it.
I have not tested the second one yet, but it seems promising.

[benjamin-heasly]

The second tool, mtoc++ looks pretty nice. It makes output like this:
http://www.morepas.org/software/mtocpp/docs/classexamples_1_1_class.html

One novel feature is that it post-processes the HTML output from Doxygen. This allows it to do some nice things, like putting multiple function returns in a comma-separated list, like so:

[a, b, c] = foo(d, e, f)

It does other interesting things. It allows types for variables and class members, which is weird because Matlab is not typed. It handles Matlab packages, which would be nice if we used them.

It also looks like mtoc++ uses some custom CSS and customizes some of the output names, like replacing the word "Modules" with "Miscellaneous".

But overall, the output is not that different from our own oom2cpp. For example,
http://davidbrainard.github.com/RenderToolbox3/docs/html/group___utilities.html

My sense is that it would be easy to crib niceties like comma-separated output lists, and nicer CSS.

But adopting mtoc++ as a new dependency might not be worth the config, unless we plan to use some of its the other features.

[DavidBrainard]

Nicolas Cottaris has been working on Doxygen tools for Matlab and has some that seem to work better than the one we're using. We should see if it makes sense to change over to what he has found/developed.

[benjamin-heasly]

Nicolas Cottaris sent me some links about using m2cpp. I plan to adopt his approach:

My latest approach is to use the mtocpp pre- and post-processing filters.
I wrote a couple of pages on our Lab's Dokuwiki as I was doing this.

The page about installing and compiling mtocpp can be found at:
http://skate.psych.upenn.edu/BrainardLab/doku.php?id=private:labadmin:sysadminprocedures:doxygen_mtocpp_filter_installation

The page about using the mtocpp filters with a Matlab class or a directory of Matlab functions, can be found at:
http://skate.psych.upenn.edu/BrainardLab/doku.php?id=private:labstuff:labsoftware:softwaredocumentation:doxygenhowto

Finally, the Matlab functions that I wrote to manage the pre- and post-processing filters can be found
on our SVN server at: https://platypus.psych.upenn.edu/repos/toolboxes/Classes/trunk/DoxygenDocumentation/

[DavidBrainard]

For 1.0, just make sure to run the Doxygen filter so it is up to date.

[benjamin-heasly]

Regenerating the Doxygen docs is now covered in issue #38.

I'm moving this issue back out of version 1.0.