Download Submission

Code covered by the BSD License  

Highlights from
Using Doxygen with Matlab

4.70588

4.7 | 19 ratings Rate this file 52 Downloads (last 30 days) File Size: 87.4 KB File ID: #25925
image thumbnail

Using Doxygen with Matlab

by Fabrice

 

23 Nov 2009 (Updated 06 Apr 2011)

Extracts automatically comments from your Matlab .m files using Doxygen to generate documentation

| Watch this File

File Information
Description

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)

MATLAB release MATLAB 7.6 (R2008a)
Other requirements - works with Matlab R2008a to R2010b - Doxygen 1.5.9 or newer required (tested with version 1.7.2) - perl required (usually shipped with Matlab)
Tags for This File  
Everyone's Tags
Tags I've Applied
Add New Tags Please login to tag files.
Comments and Ratings (47)
18 Sep 2012 CarlitosAguilar

Great contribution, thanks a lot!
19 Dec 2011 Tom

Dear Fabrice,
is your package able to document code that uses the old class specification (before use of "classdef")?

Thanks a lot,
Tom
26 Oct 2011 Brian  
27 Sep 2011 Eckard

Hello everyone

I get an error by using the pearl-script like follows:

Reading and parsing tag files
Preprocessing D:/Daten/Projekt../src/fcn.m...
Can't use an undefined value as filehandle reference at D:\Daten\Projekt\..\Filter\m2cpp.pl line 47 (formaly line 53).
Parsing file D:/Daten/Projekt/../src/fcn.m...

I tried to implent the patches from Bastian (07.07.2011) but the only the line-number changed from 43 to 47.

I use the pearl-version of Matlab 2009b on windows XP-SP3 together with Doxygen version 1.7.4

Thanks for your help,
Eckard Klotz.

09 Jul 2011 Bastien

Fabrice,
thanks again for this wonderful script.

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
07 Jul 2011 Bastien

Fabrice,
I have solved the previous package problem modifying the PERL script m2cpp.pl:

at line 42 (after the foreach $my_fic)
$packages = "";
if ($my_fic =~ /^[^\+]*\+(.*)[\/\\].*\.m/g){
$packages = $1.".";
$packages =~ s/[\/\\]\+/\./g;
}

at lines 176 and 180 (when defining $classDef:
replace: $classDef = "class ".$className
by: $classDef = "class ".$package.$className

With this patch, your code will be compatible with the Matlab Packages!
07 Jul 2011 Bastien

Fabrice, thanks for this nice script.

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 :-)
26 Apr 2011 Ian

Wonderful interface to doxygen, very easy to implement.

One very small niggle is the shebang at the top of the perl script in the latest update points to perl.exe -- this needs to be edited before it will work on *nix / OS X...
11 Apr 2011 LeFlaux

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:

foo/private/stuff.m % works
foo/@myclass/stuff.m % works
foo/@myclass/private/stuff.m % won't appear in doxygen

Regards

06 Apr 2011 Fabrice

LeFlaux, I guess you problem is a Doxygen issue (maybe the EXTRACT_PRIVATE is set to NO in your Doxyfile). If not, could you send me a test case so that I can reproduce your problem ?
25 Mar 2011 LeFlaux

Dear Fabrice,

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?
23 Mar 2011 Vincent

The same problem (see the post of the 11 Mar 2011) happens when the attribute name begins with "end" (for instance "endDate").
22 Mar 2011 guillaume

Thx a lot for this great tool !
18 Mar 2011 Vincent

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
11 Mar 2011 Evgeny Pr

Hi Fabrice,

I noticed a small problem. At multiple inheritance from a class from a package-directory the base class name is defined incorrectly.

For example:
+My - package-directory
BaseClass.m - base class in +My directory
SomeClass.m - some class in +My directory

"SomeClass" define:
classdef SomeClass < My.BaseClass
end

When you create a documentation obtained that SomeClass is inherited from the "My", a not from "My.BaseClass" or "BaseClass". :)

02 Mar 2011 Fabrice

Hi Cedric,

- 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)

Regards,

Fabrice
16 Feb 2011 Cedric Boudinet

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 (é, è, ...)

22 Jan 2011 Jack

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



% ======================================================================
%> @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
%>
%> @retval out1 return value for the first output variable
% ======================================================================
function [out1] = fb( arg1)
out1 = arg2;
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.

11 Dec 2010 Mikhail Konnik

Thanks for the update, Fabrice! Works perfect.
Linux users may find my tweaked Doxyfile for this m2cpp.pl tool useful:
http://mikhailkonnik.pbworks.com/w/file/matlab2doxygen.zip

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?
08 Dec 2010 LeFlaux

Just awesome! :) Thank You very much for this tool!

Note on m2cpp.pl: Linux users should change the first line to
#!/usr/bin/perl

18 Nov 2010 Guillaume JACQUENOT

This seems a good function.

I notice a small bug

When I declare a function on several lines, the different arguments are not recognized

For example, something like this will produce warning, and won't be correctly displayed

%> @param AAAAAA
%> @param BBBBBBBB
%> @param CCCC
%> @param DDDDDDDD
%> @param EEEEEEEEEE
%>
%> @retval Res return value for the first output variable
%> @retval RTex return value for the second output variable

function [Res,RTex] = Compute_residual(AAAAAA,BBBBBBBB,...
CCCC,...
DDDDDDDD,...
EEEEEEEEEE)
12 Nov 2010 Fabrice

I have just updated the m2cpp.pl script to better support :
- @-folder class definition
- multiple class inheritance (classdef a < b & c)
- classes attributes (Sealed, Hidden,...)
- events (transformed into enum Events in the generated documentation)
- private / protected / pubic methods
- private / protected / pubic properties
- constant properties (with their initialization)
- abstract classes (transformed into virtual functions in the generated documentation)
- the ignored argument (~) in function declaration is now read and transformed into an ignoredArg in the generated documentation
10 Nov 2010 Evgeny Pr

Fabrice, please, update your files on fileexchange. Last version works fine!
09 Nov 2010 Simon Prince

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.
26 Oct 2010 green_fr

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 ?)
26 Oct 2010 green_fr

I mean, with a brief form of abstract methods. With the following example :

methods (Abstract)
function calcPMInitiale(obj)
end
projection(obj, iteration)
end

The first method will be detected, but not the second (correct definition for MatLab).
26 Oct 2010 green_fr

But I think it doesn't work properly with abstract methods...
26 Oct 2010 green_fr  
24 Oct 2010 Evgeny Pr

A small correction to define classes (classdef (Hidden, Sealed) SomeClass) are handled correctly:
if (/(^\s*classdef)\s*(\s*\([\w,\s]+\s*\))?\s*([\w\d_]+)\s*<?\s*([\w\d_]+)?(.*)/)

24 Oct 2010 Evgeny Pr

I think the problem with this line in the file "m2cpp pl":
if (/(^\s*classdef)\s*(\s*\(Enumeration\s*\))?\s*([\w\d_]+)\s*;
}

This works, but I think it is not quite correct.
23 Oct 2010 Evgeny Pr

Hello!

I've found a bug.
Define a class with attributes:
classdef (Hidden) SomeClass < handle
end
...or with any other class attribute.
Such a definition is Parsed incorrectly.

Fabrice, You could fix this bug?
I don't understand anything in Perl. :)
21 Oct 2010 Evgeny Pr

Hello!
Do not use Perl, which comes with Matlab! It does not work correctly. Use ActivePerl.

12 Oct 2010 Erik Gudmundson

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!

29 Sep 2010 Mike

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?
17 Sep 2010 Felix

Thank you very much for this great tool.

Could it be that class hierarchies are not properly detected when the classes are in a package?
13 Aug 2010 Matt McDonnell

Fabrice,
Thanks for looking in to this, changing the extension from m to .m fixed the problem with 1.7.1.
04 Aug 2010 Fabrice

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 ?
30 Jul 2010 Matt McDonnell

Very nice tool - many thanks!
I found I had to use Doxygen 1.6.1, not 1.7.1 (latest).
I see from http://stackoverflow.com/questions/2701671/problem-with-input-filter-using-doxygen-1-6-3-on-windows-xp
you've seen something similar before.
21 May 2010 Fabrice

Ed,
I changed the m2cpp.pl file so that unix users can use it.
Thanks for your feedback.
21 May 2010 Ed

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.
07 May 2010 Fabrice

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

06 May 2010 Mikhail Konnik

Fabrice, thank for the program!
The only question I have: is it possible to comment variables by such script? I mean, if I have

a = [1,2,3,4]; %> this is a description of the var

can it be displayed in doxygen-generated docs?
02 May 2010 Fabrice

Lien-Chi,

Maybe your perl exe is not properly installed (it seems it is the case for the perl provided by Matlab). You could try the following workarounds :

1. Set the following variables in the Doxyfile :
INPUT_FILTER=perl m2cpp.pl
FILE_PATTERNS=*.m

2. If it doesn't work you should try to install ActivePerl : with this version of perl, everything is working fine.
30 Apr 2010 Lien-Chi

Why I got the following message? "Argument must contain filename -1 at C:\Users\user\Desktop\DoxygenMatlab\m2cpp.pl line 4"
30 Mar 2010 Joydeep

Nice! Would be useful if it can also generate enum classes by handling something like this,

classdef(Enumeration) Color < int32

enumeration
Red(0)
Green(1)
Yellow(2)
end

end
30 Mar 2010 Joydeep  
03 Feb 2010 Raymond

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!
Please login to add a comment or rating.
Updates
14 Nov 2010

Added support for :
* @-folder for classes
* multiple inheritance
* class attributes
* private / protected / public properties and methods
* abstract methods
* constant properties
* events
* ignored arguments (~)
06 Apr 2011

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)
Tag Activity for this File
Tag Applied By Date/Time
doxygen Fabrice 15 Nov 2010 13:37:38
documentation Fabrice 15 Nov 2010 13:37:38
documentation generation Fabrice 15 Nov 2010 13:37:38
documentation generator Fabrice 15 Nov 2010 13:37:38
extract documentation Fabrice 15 Nov 2010 13:37:38
development environment Fabrice 15 Nov 2010 13:37:38
doc help doc Fabrice 15 Nov 2010 13:37:38
development Fabrice 15 Nov 2010 13:37:38
doxygen Anthony 21 Sep 2011 07:13:18
extract documentation Pascal 11 Apr 2012 09:38:02
development Pascal 11 Apr 2012 09:38:05
development environment Pascal 11 Apr 2012 09:38:16
doc help doc Pascal 11 Apr 2012 09:41:45

Contact us at [email protected]