Code covered by the BSD License  

Highlights from
mtoc++ - Doxygen filter for Matlab and tools

4.66667

4.7 | 32 ratings Rate this file 41 Downloads (last 30 days) File Size: 579 KB File ID: #33826

mtoc++ - Doxygen filter for Matlab and tools

by

 

18 Nov 2011 (Updated )

Create nice documentation for your MatLab project using doxygen

| Watch this File

File Information
Description

This somewhat larger project allows to create 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, Mac 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
- HTML and LaTeX output
- 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.14 (R2012a)
Other requirements use: doxygen; compilation: ragel, cmake
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (77)
15 Aug 2014 Torbjörn Widhe

Hi again,

I solved the issue by upgrading ubuntu to 14.04 and reinstalling mtoc++. Now it is working like a charm, thanks again!

/Torbjörn

07 Aug 2014 Torbjörn Widhe

Hi Daniel,

thanks a lot for this great tool. I recently used it in a project on the windows platform and was very happy with it. However, I will now do a project on a linux platform and unfortunately I get parse error during post processing. I have boiled it down to the following:

My test m-file is very simple:
function c=foo(a,b)
c = a+b;

and when I run MatlabDocMaker.create, I get the following error in warnings.log

mtoc++ postprocessor messages:
/home/widhe/git/solar/matlab/qrt_toolbox/doc/foo_8m.html: PARSE ERROR
/>
&lt; matlabtypesubstitute, c &gt;&#160;</td><td class="memItemRight" valign="bottom"><a class="e

If I remove the return value like this:
function foo(a,b)
c = a+b;

everything works as expected.

I have also tried to run the failing m-code on windows without any problems (exactly the same configuration files etc), which leads me to think this is a linux problem.

I compiled according to the instructions on http://www.morepas.org/software/mtocpp/docs/install.html. During make install I get similar parse errors (I think the documentation is build using mtocpp during make install, is that correct?). Anyway, after make install, make test seems to work:

widhe@fluffy:build$ make test
Running tests...
Test project /home/widhe/install/mtoc++/mtoc++_1.5/build
Start 1: MTOCPP_TEST
1/2 Test #1: MTOCPP_TEST ...................... Passed 0.11 sec
Start 2: MTOCPP_DOXYTEST
2/2 Test #2: MTOCPP_DOXYTEST .................. Passed 0.03 sec

100% tests passed, 0 tests failed out of 2

Total Test time (real) = 0.14 sec

I'm running ubuntu server 12.04
mtoc++ version 1.5
doxygen version 1.8.7
ragel version 6.7
gcc version 4.6.3

Any help greatly appreciated!
/Torbjörn

23 Jun 2014 Daniel

Hey, very nice tool, BUT:
It does not work if you declare methods of classes with spaces between the braces.

For example:
function myFun ( in1, in2 )
...
end

I often do this for better readability so maybe you could consider taking this into account.

Thanks
D

09 Jun 2014 Hong  
15 Apr 2014 Hartmut

Very nice tool.

A question though: I have a number of functions that forward their (optional) arguments via varargin like:

%
% Parameters:
% varagin: optional parameters
% a1: argument 1
% a2: argument 2
%
function foo(varargin)
baz(varargin)
end

Works nicely but mtoc++ inserts a 'Required Parameters for varargin' before the a1, ... list. Is there a way to make it print 'Optional parameters for varargin'?

Thanks,
harti
I

16 Jan 2014 Kenneth Hsu

Hi Daniel,

Thanks for this fantastic tool. I think am encountering some strange behavior related to Bjornar's comment below.

For method blocks where only the function signatures appear (actual function code is in a separate file), the functions are not parsed properly unless there is a blank newline between the function signatures.

For example, the below results in incorrect output:

classdef Test

methods
f = myclassmethod1(obj, x, y)
f = myclassmethod2(obj, x, y)
end

end

While adding a newline results in correct output:

classdef Test

methods
f = myclassmethod1(obj, x, y)

f = myclassmethod2(obj, x, y)
end

end

Is this behavior expected? I would prefer not to have to add excessive newlines in the code.

Thanks again!

31 Oct 2013 Daniel Wirtz

hey folks,
thanks alexander! that is precisely the issue. the reason for that is that mtoc++ is a mere filter for doxygen and is not "aware" of filesystem-spanning content as is the case for distributed class definitions. so, by including the according function declaration (as actually also is valid syntax in matlab for specifying method properties) in the main file, doxygen recognizes the function belongs to that class and everything is nice & sweet!

30 Oct 2013 Bjørnar

Thanks, Alexander :-)
Actually I found out that both of the following two syntaxes work:

methods
f = myclassmethod(obj,x,y,c);
end % methods
%%%%%%%%%%
methods
function f = myclassmethod(obj,x,y,c)
end
end % methods

best regards, Bjørnar

30 Oct 2013 Alexander

@Bjornar, maybe I can comment on this, as I had the same issue.
You must put a:

methods
function classmethod(obj,x,y,c)
end

declaration in your class file. Then it works.

Best regards,
Alexander

30 Oct 2013 Bjørnar

Thanks for nice application!
However, I have some problems with parsing of files in a class subfolder. In my project I have defined a class in a separate folder, with class methods defined in separate files in that folder. When I run MatlabDocMaker.create, I notice that only the class definition file is parsed properly. For the other files only the function name and link to the class is shown in the documentation. Comments and LaTEX commands are ignored. If I move the same file to a location outside this class folder, it is parsed normally. I cannot figure out what I have done wrong.

10 Sep 2013 Guillermo

Nice work! It seems that the download links are broken, can you update them please... Thanks!

30 Aug 2013 Daryl

Very nice.

Question about enumeration classes: Are they supported? I get an error on parsing of the enumeration keyword.

Thanks.

21 Aug 2013 Martin

@Jong-Min:

To your first question:

mtoc++ does not change the byte sequence of characters. A test with Korean and Chinese characters therefore worked seamlessly for me. However, doxygen assumes all input files to be UTF-8 encoded. If this is not true for your source files, you need to change the INPUT_ENCODING configuration flag. Also make sure that your browser is configured to interpret the html output correctly.

To your second question:

You can use every doxygen formatting command in your comments...

19 Aug 2013 Alexander

Hello Daniel,

just a short feedback! If someone forgets to set the defaultvalue in the addParamValue method of inputParser
m2cpp crashes.

e.g.:
par.addParamValue('resp_opt');

not very critical but might be easily fixed.

However, all the rest works fine.

best regards,
Alexander

17 Aug 2013 Jong-Min Byun

It's great stuff!

While trying, I have some questions.

First, Does it support two bytes character (e.g. Korean, Japanese, Chinese etc) ? Source code containing both Korean and English comments shows abnormal symbols in output html.

Second, it automatically detects appropriate comments. But can I explicitly indicate comments to be used in html output using "@" symbol like classic doxygen document?

Thank you.

24 Jul 2013 Maxime

just great !! and thanks a lot for the %@@remove %@@endremove commands !!

23 Jul 2013 Pete

Sorry, ignore my last comment. I must have just screwed something up. I've done a fresh install on a different machine and everything works fine using MatlabDocMaker.create('latex',true)

My bad. Many thanks for your continued support!

23 Jul 2013 Thierry Dalon

I appreciate the really reactive and good support!

22 Jul 2013 Daniel Wirtz

Hey Pete,

please make sure you read the documentation, the answers are in there (Section: Configuration and use of mtoc++)

Anyways, if you decide to NOT use the MatlabDocMaker.create('latex',true) option, you will have to set up doxygen with latex output and mtoc++-support for your own. See the "Using mtoc++ directly" section in the mtoc++ documentation.

The other errors look like a doxygen/latex related issue, which is not our deal :-) note that mtoc++ only partly supports latex output, as the postprocessor does not work correctly on .tex files (its designed for HTML output)

I hope that helps!

18 Jul 2013 Pete

I'm trying to compress the output into 1 file. It seemed like the best way to go is enable the latex output, and then run pdflatex on refman.tex

That produces 3 errors though. Not sure if it's my fault or the package. The errors are:

refman.tex, line 41 [just before makeindex]: /doxygen/config/latexextras.sty not found

refman.tex, line 73 [\input{todo}]: 'something wrong--perhaps a missing item'. Caused by the first line: \item\contentsline{section}{+homedir/\hyperlink{_contents_8m}{Contents.\-m} \\*========================================================================= \subsubsection*{MYTOOLBOXNAME package listing \mbox{[}Version 1.\-3 10-\/\-May-\/2013\mbox{]}}}{\pageref{_contents_8m}}{}

refman.tex, line 81 [\input{files}]: Leaders not followed by proper glue

Commenting out these lines allows a workable pdf to be produced. But I was wondered if there were some simple fixes, particularly for the first 2 errors? (Or generally a better way of compressing things down into 1 file?)

16 Jul 2013 Alexander

Sorry, I meant Daniel... too many compilations confused my brain

16 Jul 2013 Daniel Wirtz

David? :-)

16 Jul 2013 Alexander

Hey David,

thanks for fixing the @folder issues with classes. Now MatlabDocMaker identifies all class methods and members.

Very nice and useful code for Matlab documentation using Matlab.

Best regards,
Alexander

25 Jun 2013 Daniel Wirtz

Hey David,
mtoc++ is "only" a filter for doxygen, which is the actual workhorse in order to produce documentation. additionally, we provide easy access to the configuration and generation of documentation from within matlab, which is why people continuously think mtoc++ is doing all the work :-)
however, in the end doxygen is in charge of producing the output (html,tex, etc), there is little we can do about it witout larger efforts. and as free time is the limiting resource here, i dont see that happen any time soon..sorry!

18 Jun 2013 David Goldsmith

Hi! I checked http://www.morepas.org/software/mtocpp/docs/index.html for a FAQ (couldn't find one; might be a useful thing to have there) before asking this: does mtoc++'s output "play nice" with Matlab's "Display Custom Documentation" features?

13 Jun 2013 Alexander  
13 Jun 2013 Alexander

Hi Daniel,

thanks for the code and the opportunity to use doxyden with matlab. Could it be that @folders for classes are not considered right for the windows version because they are not up to date?

Here comes the output from the MatlabDocMaker.create that make sme wondering that I am still in the 1.4. world.

Br,

Alexander

[Required] Checking for doxygen... found 1.8.4
[Required] Checking for mtoc++... found 1.4
[Recommended] Checking for dot... found dot - graphviz version 2.28.0 (20110507.0327)
[Recommended] Checking for latex... found MiKTeX-pdfTeX 2.9.4535 (1.40.13) (MiKTeX 2.9 64-bit)

21 May 2013 Ajaxel  
17 Apr 2013 Maxime

Hi,

after some experiments, i think it's a doxygen trouble, because i've got the same results with C++ codes. Or it's a bad configuration of doxygen, but i tried a lot things...

I'm not sure if doxygen is able to do such a thing, but i asked them if i was mistaking. I will give you some infos when i have got some.

Maybe i'm not the only user needing this capability, and it should be great to have a special tag to remove some code from the documentation, for example "% remove this code from the documentation" and "% end of removal"

Thank you for your work,

Maxime

12 Apr 2013 Maxime

hi, thank you for your response.

the \cond and \endcond commands work fine when they are in the description of the function.

When they are used in the code, in order to exclude some part of the code, they don't work.

Here is a simple example, where i don't want to show the lines between \cond and \endcond in the generated code.

function [c] = sumM(a,b)
% sum function
%
% sum function detail description.
%
% Parameters:
% a : first data of type double
% b : second data of type double
%
% Return values:
% c : sum of a and b

% comment
c = a + b;

% \cond
% dummy code to exclude from the documentation
disp('function is ok')
% \endcond

I think that mtoc++ should analyse wether a commented line in the code begins with some special commands. Or maybe i don't use correctly your (great !!) tool.

Thank you !

Maxime

12 Apr 2013 Daniel Wirtz

Hey Maxime,
well those commands are purely doxygen-related and probably require a concurrent version; i would not expect any other difficulties with those commands in connection with mtoc++.
However, if you have reason to believe it might be caused by mtoc++, please send us some more details, logs etc.
Thanks, Daniel

11 Apr 2013 Maxime

Hi,

Great job, and thank you for the last updates which make possible to include code and dependencies graphs !!

I would like now to use the special command \cond and \endcond to exclude some part of the code to the documentation.

I didn't succeded ; do you think it possible ? How should i do that ?

Thank you,

Maxime

02 Apr 2013 Evgeny Pr

@Daniel Wirtz

Excellent! I built mtoc++ from the last update. It works! :)
Thanks!

31 Mar 2013 Daniel Wirtz

Hey Evgeny,
i'm not surprised by the Grrr! message for events; we simply haven't included parsing special modifiers for event blocks, as we ourselves rarely make use of them yet. but i'll spend some time next week digging into that. the "-" will be no problem.

31 Mar 2013 Evgeny Pr

Another parse error in:
"events (Hidden, NotifyAccess = private, ListenAccess = public)"

Message: Grrrr!!!!
Next 20 characters to parse:
NotifyAccess = priva
------------------------------------
States are: ClassPart: Event
PropParams: constant = 0
MethodParams:
AccessStruct: full = Public get = Public set = Public

31 Mar 2013 Evgeny Pr

Hello!

Thanks for very useful and powerfull util.
A small wish: Please, add the "-" symbol in function "getProjPrefTag" of class "MatlabDocMaker".

I get an error "Invalid field name" if my project name has symbol "-", for example: "My-Project".

Thanks!

28 Mar 2013 Pete

Everything fixed from my last comment (below). Now working very nicely, even with many bits of new (2012) syntax. Great stuff!

25 Feb 2013 Pete

Having used this package for a few days, I remain hugely impressed by it. The parser does struggle with a couple of aspects of my code though; it would be great if these could be fixed:

- It does not like Abstract in the class definition [e.g., classdef (Abstract) MyClass < MySuperClass]

- It does not like class-specific references in the Access declaration for a method [e.g., methods (Static, Access = ?MyClass)]

- It does not like quote marks around Access types [e.g., Access = 'public' ; rather than Access = public] (I'm not sure whether using quote marks is considered good or bad practice? But since both are accepted by Matlab, it would be handy if both were catered for)

(n.b., the first two things have only been valid syntax since 2012, so not really surprising that they aren't catered for, but I do use them extensively in my code, so would be great to get them working).

@Daniel. In terms of what I found daunting about installing. I guess there were two aspects. Firstly, there was compiling everything and building the dependencies. Installing all the other software in turn meant extensively updating my *very* old version of MacPorts. All the various steps took a while to download/unpack and I was convinced some link in the chain was going to break (quite a few errors were spit out along the way, but by some miracle everything worked fine in the end). To be honest none of this is the fault of this package per se, and you can't very well distribute all the third party software. But I just know quite a few people may have given up along the way. The second issue, was getting Matlab to recognise where the various dependencies (e.g., Ragel, Latex) were installed. I got a bit confused at one point, because the necessary directories were on my terminal $path, but not on Matlab's system path. I still don't really know if editing the Matlab executable was the best way to go about getting them recognised (and again, I think a lot of people would be put off doing that), but hey, it worked. Like I say, I don't think either of these things are really things you can do much about, and I think all the crucial information is in the documentation. I just think that the average Matlab user will think twice before installing this package, which is a shame since it's a really nice bit of work. (Then again, the average Matlab user probably doesn't want this package in the first place, so maybe this is a moot point.)

Oh, and have just installed it on Windows 7 too. Easy installation, working fine no problems.

22 Feb 2013 Aurelien Queffurust

Hi!
I've just tested 1.5 version . Previous bugs of hyperlink and different versions of Matlbdocmaker are fixed. Thanks.
There is no more issue in the log concerning the path of logo .
Howewer the logo is not included in the Doxygen project , instead it is just written Logo. FYI , I use a jpeg image 17kb 700*70 pixels. It is not a major issue ;)

Aurélien

21 Feb 2013 Aurelien Queffurust

Great you are really proactive!
Thanks for having answered to all my different points.
I guess your new submission on Fex will be uploaded in a few days or hours (depending on MathWorks).
I already check the new doc , cool that's clearer.
I will try your new submission and will let you know my feedback.
Thanks again for your efforts.

21 Feb 2013 Daniel Wirtz

Dear Aurelien,
thanks for your detailed feedback!

1) Your pointer lead me to a bugfix due to a wrong argument type call of MatlabDocMaker.create; however, with the previous FEX version I could reproduce exactly your claimed error.

2) This has been already reported and i've included a bugfix in my local version but didn't get around to publish it yet.

3) in fact, this is a purely doxygen related issue; it tries to interpret \archives and \seiscreen as commands, which it not knows and thus gives you a warning. the reason for the mangled line numbers is the mtoc++ filter, as the backup_seiscreen.m ist filtered (that is what mtoc++ actually does) and thus gets new line numbers; the line numbers in the warnings log of doxygen are taken from the processed files. there is generally no way of keeping those line numbers matching.

4) please read the comments below regarding the call graph. this is a feature we explicitly do not support, as mtoc++ merely transforms the syntax and not the semantics into c-compliant form. thus, function calls from within method bodies or scripts will most likely not be detected by doxygen.
A correct processing of code in order to reveal the complete call graph would require cross-file parsing at the filter level already, which we will, truth spoken, probably not implement due to the little use for our own applications and time constraints.

5) well, i'm having trouble understanding your troubles with this regard. i've rephrased some of the sentences, but essentially all you need to do is to ensure that all relevant binaries can be found on the windows PATH. that involves operating knowledge of both windows and the involved 3rd party tools, mainly doxygen. we see this as a requirement and just provide the necessary hints.

6) Yes, the last time i've updated the FEX submission i did not update the downloads on our documentation site; my apologies for that.

finally, i've submitted an all-current version to FEX this morning and also updated the documentation and downloads on www.morepas.org.
I'd be happy to get to know if those updates successfully addressed your issues.

regards,
Daniel

21 Feb 2013 Aurelien Queffurust

Hello,

This is my feedback (I am under Windows Xp R2011b):
1)When running MatlabDocMaker.setup, the last sentence is Run MatlabDocMaker.create. When you click on this hyperlink ,you get Undefined variable "MatlabDocMaker" or class "MatlabDocMaker.create".

-> You need to type by yourself MatlabDocMaker.create

2) MatlabDocMaker finished with warnings. When I see the log:
Project logo "'F:DOCUMENTATION_SYSTEMsolution3_mtoc estcongre.jpg' specified by PROJECT_LOGO does not exist!"

-> All file separators (filesep) have disappeared , so it cannot find my picture.

3) The 2 following sentences in the warnings.log:
"F:/DOCUMENTATION_SYSTEM/Seiscreen/backup_seiscreen.m:55: warning: Found unknown command `\archives'"
F:/DOCUMENTATION_SYSTEM/Seiscreen/backup_seiscreen.m:55: warning: Found unknown command `\seiscreen'

-> When I look at the backup_seiscreen.m, the issue first is not in line 55. In fact line 4 , there is a commented line with a path : \\10.33.42.132\archives\seiscreen
Again it does not interpret correctly file separator

4) The dependency graph is nice but could be more perfect. Let' say I have foo.m which is called by an interface main.fig from a callback called "pushbutton_test_callback" .In the caller graph I can see foo <- mtoc_subst_main_m_tsbus_cotm_pushbutton_test_callback.
Why these weird prefixes mtoc_subst_ and m_tsbus_cotm are added ?

5) I suggest to rewrite the installation steps for Windows. It got me 30 minutes to really understand what to add in my MATLAB path, environment variable (mtocpp.exe)

6) Also there are 2 different version of MatlabDocMaker mtoc___mlfex_1.4\mtoc++_1.4\tools\ and mtoc++_win_1.4\mtoc++_1.4\tools\ (folder unzipped from mtoc++_win_1.4.zip )
The most recent is from this Fex page.

I definitely prefer m2html which is plug and play with a clear installation process.

I hope my feedback will help you to improve your submission.

19 Feb 2013 Daniel Wirtz

Hey Pete,
thanks for your feedback!
If you would flick me a short email with some more information on the aspects of the installation process you feeled have been "daunting", i'm more than happy to make improvements out of it. We did not have feedback from a lot of iOS users yet!

Regarding the call graph and inline source: see my comment from [27 Sep 2012]. the answer from Dimitri (doxygen developer) was:
"Doxygen extracts call graph information while processing the source files for the code browser view (SOURCE_BROWSER=YES).
So when this view shows the source code as-is, doxygen doesn't see the functions that make up the call graph.
Setting FILTER_SOURCE_FILES to YES should fix this (but will show filtered sources in the code browser).

Getting both unprocessed code in the source browser and proper call-graphs would require 2 parsing passes, which is possible,
but not implemented at the moment."

so, you can show the sources (either via browser or inline), which will display the unmodified version (but probably with grossly wrong line numbers, as the references to the lines where e.g. a function has been detected comes from the mtoc++-processed m-file).
now, if you use FILTER_SOURCE_FILES the call graph might get a bit more complete, however, it will most likely still be incomplete. here's why: the complete functions' interior needs to be transformed into correct c syntax, so that doxygen can detect/read calls and create the call graph. but so far mtoc++ does not parse function bodies, as this would require a whole lot more than a single-file-at-a-time walkthrough.
additionally, another downside of FILTER_SOURCE_FILES, you will get mangled matlab code in your source browsers and views. in order to alleviate that, we changed the mtoc++ filter to leave non-relevant code "as-is" with correct indentation, so that this at least does not look too aweful.

best,
Daniel

18 Feb 2013 Pete

I compared this with the similar fileexchange entry http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab, as well as with matlab's own built-in documenting tools.

This seems to be the best for situations such as mine, where I want to document object-oriented code spread over different packages. It is particularly forgiving in terms of how it parses comments, meaning that (after a bit of tweaking) I have comments that render well using 'help x', 'doc x', *and* which produce a beautiful doxygen html.

Installation was a little daunting and took about 30-45 mins (the supplied documentation was invaluable here). However, it was definitely worth the effort. Oh, and just for the record: I don't know if this is the best solution, but to ensure that the Matlab script could find the necessary resources, I opened /Applications/MATLAB_R2010a.app/bin/Matlab in TextEdit, and added the line "export PATH=$PATH:/usr/local/bin/:/usr/texbin" (without quotes), directly after the comments. Seemed to do the job (n.b. Mac OS X).

This is a great tool, and one which I look forward to using extensively over the coming months.

(btw, I second Maxime's [06 Jul 2012] comment)

11 Oct 2012 Daniel Wirtz

Dear Francois,
the file "latexextras.sty" is not included, as it is generated by the MatLabDocMaker upon "create". This is done on purpose, as the paths in the style file might need to be adjusted.
There is a file "latexextras.m4" in the tools/config folder of the submission, this is the file you need to change in order to include more stuff. Have a look at it!
Cheers,
Daniel

10 Oct 2012 Francois Rongère

Hi Daniel,

I can't manage to find the latexextras.sty style file for latex document generation in the archive.

The result is that I can't build the refman.tex through the MakeFile generated by Doxygen.

Is it a missing file or do I have to provide one on my own ?

05 Oct 2012 Wolfgang

Hi Daniel,
you did a very good job with this tool, I have two points to add:
I modified the MatlabDocMaker.m file such to support the project logo. Are you interested in that? I could sent it to you via mail. I added and changed only some lines.

Second:
In the LaTeX output, there are a lot of words like "matlabtypesubstitute" and things like that:
mlhsSubst< mlhsInnerSubst
< matlabtypesubstitute, AR >
,mlhsInnerSubst
< matlabtypesubstitute, angVal >

Do you know where this comes from and how I can remove this?

Thank you very much for your help and your effort.

Wolfgang

27 Sep 2012 Francois Rongère

Thank you Daniel :)

27 Sep 2012 Daniel Wirtz

hey maxime,
it seems like it is not possible to use these features of files that are processed by filters like mtoc++.
so even though this is not a mtoc++-related issue, we do think it is of interest to enable those features also wiith filters included, we've contacted the doxygen team to see what can be done.
stay tuned!

27 Sep 2012 Daniel Wirtz

dear francois, your issue has been resolved and will be published with our next release on FEX soon!

03 Sep 2012 Francois Rongère  
27 Aug 2012 Francois Rongère

Oups sorry for the rating, its a mistake I didn't want to use it for the latter post.

27 Aug 2012 Francois Rongère

I did a little experience :

I clone the MatlabDocMaker.m file which is well parsed by mtocpp and I give it an other name such as exampmle.m
It the latter, I change the fist word classdef with function.
I run mtocpp (MatlabDocMaker.create) to produce the documentation of all files, example.m included.

Now I have also a segfault on example.m.
What'qs wrong with the function keyword ?

Best wishes

François

27 Aug 2012 Francois Rongère

Hi,

Thank you for this piece of software.

However I have a problem with a segfault by doxygen which does not like simple function files.
The example file structArgFunc.m which is not a class file yields to a segmentation fault at the preprocessing stage of doxygen so I suppose that this error appears when the mtocpp filter is applied on the file.
Dos somebody had this kind of issue ?

Thanks in advance
Regards
François

09 Jul 2012 Maxime

for your information, i'm working on Windows. Thanks for your help !

06 Jul 2012 Maxime

Hi,

first of all, thank you for these great and amazing tools.

I would like to know if MTOC++ is compatible with these 2 docygen's options :
- call graph and called by graph, to show dependancies between function (not only classes), using the dot tool
- INLINE_SOURCE to include the body of functions and classes directly in the documentation

I tried to activate these 2 options, but it doesn't seem to work with simple matlab function (see example below), even if it works fine with C or C++ code.

Thank you for your help,

Maxime

------ test1.m ------

function [imaOut] = test1(ima,alpha)
% fonction de test

in = alpha * ima;
c = somme (4,2);
in = in + c;
imaOut = test2 (in,9,3);

function [imaOut] = tuty(ima,beta)
% fonction de tuty

in = alpha * ima;
c = somme (4,2);
in = in + c;
imaOut = test2 (in,9,3);

------ test2.m ------

function [imaOut] = test2(ima,a,b)
% autre fonction de test

imaOut = a * ima + b;

------ somme.m ------

function [c] = somme(a,b)
% fonction de somme
%
% Parameters:
% a: 1ere valeur
% b: 2ere valeur
%
% Return values:
% c: sortie

c = a + b;

29 May 2012 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

15 May 2012 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?

06 May 2012 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.

05 May 2012 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!------------------

07 Feb 2012 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

24 Jan 2012 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!

14 Jan 2012 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!

13 Jan 2012 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

05 Jan 2012 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.

28 Dec 2011 Catalin Lupu  
28 Dec 2011 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

12 Dec 2011 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.

11 Dec 2011 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!

10 Dec 2011 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.

10 Dec 2011 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.

10 Dec 2011 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.

10 Dec 2011 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!

04 Dec 2011 Evgeny Pr

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

04 Dec 2011 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

04 Dec 2011 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?

04 Dec 2011 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!

Updates
23 Nov 2011

Included a logo :-)
Currently working on Windows version.

25 Nov 2011

- Now having fake standard matlab datatypes available for the @type tag (Included a file class_substitutes.c into the config folder)
- Some updates to the example classes

30 Nov 2011

- Added support for Windows platforms!
- Some smaller improvements

08 Dec 2011

Fixed the bug described by Evgeny Pr
(External Windows binaries will be updated soon)

13 Jan 2012

- Fixed the 'AbortSet' issue reported by Catalin Lupu
- Allowing multiple line default values in property comments
- no more "couldn't resolve reference to dw" errors
- smaller fixes

for a complete list see our documentation changelist!

16 Jan 2012

Fixed a bug that caused latex build errors on Windows platforms due to the wrong file separator in the doxygen-tag EXTRA_PACKAGES

17 Jan 2012

After long correspondence with Roland M now finally fixed problems with windows platforms.

04 Mar 2012

Updated submission to current working version with license-related updates

19 Nov 2012

mtoc++:
- many bugfixes
- added varargin support
MatlabDocMaker:
- can now also create LaTeX docs
- source browsing enabled by default

For a complete list of changes please visit www.morepas.org/software/mtocpp!

19 Nov 2012

Accidentally included test case html (removed)

11 Feb 2013

Bugfix for Windows Paths (Thanks to Arvind Jayaraman from MathWorks and Chris Olien for reporting!)

21 Feb 2013

- Smaller bugfixes (see changelog)
- Started mtoc++ 1.5

29 Mar 2013

Included suggestions from Pete:
- 'Abstract' class modifier allowed
- Quotes for access modifiers (e.g. 'private'
- Class-specific method/property access supported

02 Apr 2013

- Now also parsing Event Access modifiers
- Small bugfix in MatlabDocMaker

26 Jun 2013

Increased postprocessor robustness. A parser error does no longer cause the overall postprocessing to stop

15 Jul 2013

Bugfix: Comments directly before "end" tags broke the parser.

23 Jul 2013

- Started a FAQ
- Smaller parser errors fixed

Contact us