Make Doxygen output more Matlab-esque

[benjamin-heasly]

Issue by benjamin-heasly Thursday Feb 14, 2013 at 22:51 GMT Originally opened as https://github.com/DavidBrainard/RenderToolbox3/issues/9

---

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]

Comment by benjamin-heasly Thursday Feb 21, 2013 at 17:47 GMT

---

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]

Comment by benjamin-heasly Tuesday Feb 26, 2013 at 19:41 GMT

---

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.

[benjamin-heasly]

Comment by DavidBrainard Wednesday May 01, 2013 at 13:42 GMT

---

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]

Comment by benjamin-heasly Thursday Jun 06, 2013 at 15:46 GMT

---

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/

[benjamin-heasly]

Comment by DavidBrainard Thursday Jul 18, 2013 at 13:57 GMT

---

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

[benjamin-heasly]

Comment by benjamin-heasly Friday Jul 26, 2013 at 23:15 GMT

---

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

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

[benjamin-heasly]

I think our current plan is to adopt "plain old Matlab help" documentation style, and not longer think about Doxygen. We should use the "plain old help" style for new code that we write in Version 3.

We will also want to update a bunch of existing help documentation to put it in "plain old help" style. Should we make this a goal for Version 3?

[benjamin-heasly]

Closing this issue. It should be addressed in RenderToolbox4: https://github.com/RenderToolbox/RenderToolbox4