License

Copyright (c) 2009, Fabrice
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the distribution

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

This package allows you to extract automatically comments from your Matlab .m files using Doxygen to generate documentation.

This package provides :
- a perl script (m2cpp.pl) used to filter the .m files so that Doxygen can understand them
- a template for the Doxyfile file (configuration file for Doxygen) which has to be modified according to the location of your code
- documentationGuidelines.m, an .m file which describes how you should comment your code so that Doxygen can extract it and create nice documentation
- classDocumentationExample.m : an .m file describing possible comment for classes
- all the documentation (html format) automatically generated by Doxygen from the two .m files (see Doc/html/index.html), which provides informations about installation and how to write Doxygen comments.

Installation details :
- You need to have the Doxygen software installed (version 1.5.9 or newer required (tested with version 1.7.1))
- You need to have perl installed (perl is shipped with Matlab, located usually in $matlabroot\sys\perl\win32\bin)
- unzip the DoxygenMatlab.zip to C:\DoxygenMatlbab (for example)
- get the Doxyfile file from the C:\DoxygenMatlbab directory and replace the default Doxyfile provided by Doxygen
- edit the Doxyfile file (or use the DoxyWizard tool provided by Doxygen) to modify a few settings :
o EXTENSION_MAPPING=.m=C++
o FILTER_PATTERN=*m=C:\DoxygenMatlbab\m2cpp.pl
o PERL_PATH=<path to your perl version>
o INPUT=<directory where your documented code is located>
o OUTPUT_DIRECTORY=<directory where you want to generate your documentation>
o STRIP_FORM_PATH=<directory where your documented code is located>

Note for Windows users :
In certain circumstances, the association between .pl files and the perl executable is not well configured, leading to "Argument must contain filename -1 at C:\DoxygenMatlab\m2cpp.pl line 4" when running doxygen. To work around this issue, you should execute the following lines in a Windows command prompt ("cmd") :

assoc .pl=PerlScript
ftype PerlScript=C:\Program Files\MATLAB\R2010b\sys\perl\win32\bin\perl.exe %1 %*
(don't forget to replace the path to the perl.exe file with yours in the line above)

Comments and Ratings (75)

Running "dos2unix m2cpp.pl" and adjusting the FILTER_PATTERNS to FILTER_PATTERNS = perl YOUR_PATH/m2cpp.pl seems to have done the trick for me. However, the documentation that is generated does not match the one provided with DoxygenMatlab for the example files. Events are not listed and not all properties are listed, for instance. I will keep working and post a solution if I find one.

I had some trouble because either the documentation highlighting or the linking of the source files did not work properly.
After I started using m2cpp.pl as an inputfilter and not as a filter pattern, everythings seems to work as expected:

# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
# by executing (via popen()) the command <filter> <input-file>, where <filter>
# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
# input file. Doxygen will then use the output that the filter program writes
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.

INPUT_FILTER = "perl m2cpp.pl"

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the
# filter if there is a match. The filters are a list of the form:
# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
# is applied to all files.

I am generating a Doxygen documentaion for .m file.Firstly I generate it by simply editing the doxygen.conf file, I add FILE_PATTERNS= .m and EXTENSION_MAPPING= .m=c++. But it did not produce correct documentation of .m file. Now I am following your post "Using Doxygen with matlab and download "Doxygenmatlab" package. I have tried to understand all things, But unable to understand. Guide me what I have to do?

However, now finally changed to Windows 7 I get the error/warning message warning: "Warning: Found ';' while parsing initializer list! (doxygen could be confused by a macro call without semicolon)" and my .m files are not parsed any longer. Do anybody know the workaround?! (Sonsoles earlier had the same problem but didn´t posted the solution;-()

I realized that comment in the function is not possible to extract by this filter even with "%>"
And function output parameter does not reveal in the documents also, if using a "..." for line break in the function name, the filter cannot parse it correctly.

Since this distribution contains doxygen-configurations also and
with the version 1.9.08 the languages Matlab and Pascal are
supported also two third-party filters are added in the associated
LangPack folders:

Hello!! i am runing Doxygen in my matlab code and the question is, it should show some graph as well.
i got the following errors:
C:/Users/Sonsoles/Documents/Fortran/Kompressorkoden/get_o_over_c.m:23: warning: Found ';' while parsing initializer list! (doxygen could be confused by a macro call without semicolon)
C:/Users/Sonsoles/Documents/Fortran/Kompressorkoden/get_omega_s.m:21: warning: Found ';' while parsing initializer list! (doxygen could be confused by a macro call without semicolon)
C:/Users/Sonsoles/Documents/Fortran/Kompressorkoden/Xfunc.m:21: warning: class for member `M::::::calculate:' cannot be found.

I am under Windows XP R2011b. When I run Doxygen , the perl file m2cpp.pl shows up on the screen for each M-file that is processing. I have to close the file manually.
Moreover , your perl file requires to change all our syntax since the filter extracts only lines beginning with %>. For function description, same issue , we have to use a specific syntax.

The other submission "mtoc++ - Doxygen filter for Matlab and tools " is better , it doesn't require any change in our codes.

First I had problems with access rights for involved programs, had to set Run as administrator, also had to patch in registry to make perl accept command line arguments.

Then m2cpp.pl crashed at row 43. After having modified by inserting
"use FileHandle;" at first row
and replaced row 43
"open(my $in, $my_fic);"
by
"
my $in = new FileHandle; # Fix for old version of Perl
$in-> open($my_fic);
"

Actually someone helped me already to solve the problem. The file m2cpp.pl is formatted for DOS. One has to reformat it for Linux in order to get everything to work correctly (I did it with the tofrodos package). The program is great :-)

It *almost* works for me and I suspect it may have to do with a Linux problem. I receive the following error messages

sh: /media/sda5/Giovanni/Utilities/Matlab_utilities/Matlab_exchange_downloads/DoxygenMatlab/m2cpp.pl: not found

and the html files after this do nto contain any documentation (as no c++-style comments are produced). The m2cpp.pl is there, though, I have tried to move it around and I still receive corresponding error messages. Could anyone tell me where I have to start looking for solving this problem? Thanks in advance.

It would be a nice improvement to have some options to be able to hide some information in the documentation:
-> hide the Hidden methods/properties for the public APIs.
-> hide the set.my_property/get.my_property methods in the classes that are useless in the documentation

However, is it possible to include support for packages?
For example, if you have:
./+PackageName/ClassName.m
./ChildClassName.m
where ChildClassName < PackageName.ClassName, then the script combined with Doxygen will create 2 different pages for ClassName:
- one for ClassName containing the definitions of all methods and properties
- one for PackageName.ClassName containing no definition at all (just the inheritance relational graph)

Maybe you could use C++ namespaces to solve this bug?
(or maybe Java packages are more suited to implement nested packages like ./+Package1/+Package2/MyClass.m)

thanks a lot in advance if you can help with this!

PS: for those like Cedric who have some troubles with the "< handle" inheritance, you must UPDATE your Doxygen installation :-)

Fabrice, thank you for your quick response. The flag was already set to YES. However, in the meantime I realized that doxygen works for private directories located in standard folders but not in class folders:

thank you for this great and useful piece of software! Just one little question: I got directories named `private' in my Matlab-project. The documentation of .m files contained in such directories are not displayed. Any suggestions?

I experienced a little problem when using it on "@" folder class definition. As strange as it looks, when the name of my function (defined in an external .m file inside the @ folder) begins with a "m" letter, the function does not appear in the generated class description. It works just fine when I change it in another letter. Any idea?
thanks

- the inheritance syntax (classdef MyClass < handle) is fully supported by the m2cpp.pl script : could you send me a test file so that I can see why you experienced such errors using this syntax ?
- your second problem is an encoding configuration issue in your Doxyfile (you shouldn't use the UTF-8 encoding but probably the ISO8859-1 encoding)

It seems good, however I do encounter some problems: one of my scripts is a classdef deriving from 'handle' :
classdef MyClass < handle
the parser gives an error since < is not closed by a >
Is there a way to avoid this ?
Another problem is that the parser gives errors on non-ascii letters (é, è, ...)

I've been using and enjoying your product. I have a quick question though.
1)I am using Matlab 2007a with only fuctions, i.e., not classes. I cannot get doxygen to create any graphs, either using graphviz or the included graphing library. I'm familiar with doxygen, and was wondering if your product in conjunction with doxygen supports graph generation via function calls alone? I uses a similiar perl script posted somewhere online to convert from .m to .c and it could generate graphs in doxygen. Thank you for your time, the .m is included below, in which no graph is generated (I have graph generation enabled in doxygen and all the setting in expert are correct aslwell I believe).
%> @brief Brief description of the function
%>
%> More detailed description.
%>
%> \latexonly
%> $\bigl(\begin{smallmatrix}
%> a&b\\ c&d
%> \end{smallmatrix} \bigr)$
%> \endlatexonly
%>
%> @param arg1 First argument
%> @param arg2 Second argument
%>
%> @retval out1 return value for the first output variable
%> @retval out2
% ======================================================================
function [out1, out2] = hhh( arg1, arg2)
out1 = arg2;
out2 = arg1;
c = fb(out1);
end

2) when I use
/latexonly
/endlatex only
Doxygen commands to put in a matrix in latex, my matrices/equations have the "///" comment denoted for c++, this is not a problem, but if there is an easy fix I'll like to know.

By the way, does anybody know how to add citations to the documentation from Doxygen using LaTeX? I mean, one have \cite commands in the documentation, and those cited sources should appear in the doxygen-generated docs. Any ideas?

Great utility, thanks. Question about using it with multiple-file classes - I get it to work with a class in a single file, but when I set up a class in an @folder, I don't seem to get the function based methods (in separate files) located within my doxygen derived class.

Another strange point with inheritance. Imagine class Father inherited by two classes Son1 and Son2. In Father there is a method Father::doIt() overloaded by Son1::doIt(), but inherited directly from Father by Son2.
The strange point is that in Son2 documentation you’ll see comments about Father::doIt() (that is normal) followed by «Reimplemented in Son1» (that is weird — or may be this is a standard C++ documentation agreement ?)

Thank you, Fabrice, for a really nice tool! It seems, as Felix has noted, that only classes contained in one single .m-file are supported, and not the folder (@-)structure. Furthermore, the private class-properties are displayed as public ones. Is there any chance that you could fix this? I'm aware that the Matlab style of Access, SetAccess, and GetAccess might be tricky, but it would be really helpful. Thanks a lot!

Does this tool handle collaboration diagrams? When a class is composed using another class, it does not show up in the collaboration diagram. The collaboration diagram is always the same as the class diagram. Am I doing something wrong?

Matt,
I tried to use Doxygen 1.7.1 and I suppose I reproduced your problem.
I guess this is a Doxygen bug, but as a workaround, you could try to change the value of EXTENSION_MAPPING in the Doxyfile :
EXTENSION_MAPPING=.m=C++ (don't forget the dot before the 'm').
Could you tell me if it solved your problem ?

I had a problem using the script under Unix (Linux) since the first line of the perl script, which defines the interpreter to use (/usr/bin/perl), was terminated using a carriage-return (\r) instead of a line feed (\n). Because of this the perl interpreter could not be found. Since the first line only makes sense in a Unix environment, I think the line-ending character for the first line (at least) should be changed to a line-feed.

Mike, you can comment only variables outside function block (this is a Doxygen limitation), that is :
- arguments passed to functions, for example :
%> @brief Description of the foo function
%> @param a this is a description of var a
%> @param b this is a description of var b
function foo(a, b)
...
end

- properties in a classdef definition, for example :
classdef foo
properties
%> this is a description of the var a
a
%> this is a description of the var b
b
..
end
...
end

This is exactly what I was looking for, and to see that it works on subfunctions and object oriented code is simply brilliant. This is a wonderful replacement to mtoc that works wonderfully. Many kudos to the author for simplifying my life and increasing my productivity. Brilliant!

Updates

6 Apr 2011

1.8

Fixed a few bugs :
- property names (and method names) beginning with end are now allowed (as pointed out by Vincent)
- inheritance with classes containing a dot is now supported (as pointed out by Evgeni Pr)