mtoc++  1.5
mtoc++: Doxygen filter for MatLab .m files
 All Classes Namespaces Variables Pages
Configuration and use of mtoc++

Help on how to use the tools coming with mtoc++

Make sure you have followed the mtoc++ installation instructions.


Documentation creation

As mtoc++ itself is only a filter to plug into doxygen, there is little sense in calling the binaries directly.

Thus, mtoc++ comes with a series of tools that take over the documentation generation process for different interfaces.

Those tools can be found inside the <mtoc++-source-dir>/tools folder.

At some stage you will need to have access to the involved binaries like doxygen, mtocpp, mtocpp_post or latex. It is your responsibility to ensure the availability of the binaries in whatever environment you want to create the documentation. The most obvious way is to place all binaries inside a directory contained in your local PATH variable (both unix/windows). We've had reported issues with MAC users, that dont have the environment set when launching MatLab from the Dock. See Troubleshooting mtoc++ for more information.

Using the MatlabDocMaker

The most convenient way of using mtoc++ within your matlab project is to use the MatlabDocMaker class coming with mtoc++. The MatlabDocMaker is a MatLab native class that can be directly used from within MatLab in order to create the project documentation.

Follow these simple steps in order to quickly get your first documentation:

See the MatlabDocMaker class description for more details on how to use it.

You may of course keep the MatlabDocMaker.m and the configuration files where you initially placed your mtoc++ source and point to the appropriate directories during setup.
However, if you want to use multiple projects with mtoc++ you probably want to have different configurations for each project, so that is why we recommend to create local copies of your tools and configuration within each project. (The MatlabDocMaker stores its setting dependent on the name you specify for the project!)
The way the MatlabDocMaker works it can be easily inserted into whatever versioning system your project uses. As it stores important folders in MatLab preferences each developer will still have his local documentation settings (after running MatlabDocMaker.setup on each machine, of course).

Using mtoc++ directly

Okay, so you're a crack and want to control everything. That's fine with us! In this case we also assume you're familiar with whatever your operating environment is and you have solid knowledge of what's going on. First, you could simply reverse-engineer what the MatlabDocMaker is doing (it automatically generates and inserts the correct scripts read by doxygen), otherwise, here are the basic steps required to get started with mtoc++ directly. In short, this happens by including mtoc++ as a filter for *.m files:

Using the python script from a unix shell

python script, yet to come

Configuring mtoc++ and doxygen

As the configuration of doxygen/mtoc++ is independent from the actual tool used we will explain it separately. The involved files can again be found inside the /tools/config folder.

The settings in the "Doxygen.template" file inside the /tools/config folder are a default configuration for Doxygen which we thought might be useful in a MatLab setting/project and contains some changes in order to make mtoc++ run together with doxygen. We've had lots of feedback and problem reports which actually had to do with settings purely regarding doxygen, so we strongly recommend having a look through Configuration options for doxygen and the references therein before contacting us. Thanks!

Configuration options for doxygen

The Doxyfile.template file uses placeholders for specific folders etc. and contains any other configuration settings you want doxygen to use. This way, the configuration files can be included into the versioning system as local developers paths are stored outside the configuration file and are provided by the different tools coming with mtoc++.

See for more information on doxygen configuration.

Configuration options for the mtoc++ filter

The file mtocpp.conf contains additional configuration for the mtoc++ parser.

The mtoc++ filter takes exactly two arguments, of which the first is the file to process, and the second is an optional configuration file. So if you dont want to customize mtoc++ because the default settings are just fine, there is nothing to do (you simply can set the filter target in doxygen to the mtocpp binary for the manual config case). Otherwise, if you want to provide a config file to mtoc++, depending on your platform, you have to write a shell/batch script that is included as filter callback in doxygen's configuration file. Inside the script, the first argument is forwarded to mtocpp and the second configuration file path is provided statically in the script.
We recommend to use the MatlabDocMaker tool described in Using the MatlabDocMaker, as it does all that for you.

The following is a short list of options that can be specified in the configuration file for the mtoc++ filter. All options are declared by the syntax

<option> := <value>

and are optional, as the default values are hardcoded into mtoc++.

Moreover, default descriptions/values for recurring entries like parameters or field names can be specified.

Note that the configuration file sections for variables above and rules below have to be separated by a single line containing only a double hash '##'. ONLY use '##' for that purpose.
Parameter default descriptions
Use the syntax
add(params) = <parameter1_name> => """Your parameter1 description text in triple quotes""",
* <parameter2_name> => """Your parameter2 description text in triple quotes""";
to add default descriptions to parameters of functions or class members.
Struct field default descriptions
Use the syntax
add(fields) = <field_name> => """Your field description text in triple quotes""";
to add default descriptions to fields of any struct or class (identified by a ".fieldname" syntax in the MatLab code)
Extra documentation
add(doc) = """ <some extra doc for all files> """;
to append some extra documentation to each class or files documentation. Use
add(extra) = """ <text at end of comments> """;
to append text at the end of any comment.
Global settings for specific files or folder groups
More advanced, those settings above can also be made on a group-based setting. The syntax
* glob = <folder or filename (regexp allowed)> {
* <expressions as above>
* glob = <subfolder or files> {
* <expressions as above>
* };
* }
can be used to specify groups of rules that are applied to any matching file or files in folders. Nesting is possible, too.

So for example,

glob = myfile.m { add(params) = param1 => """ param 1 description """; }

would cause mtoc++ to add the description "param 1 description" to any parameter called param1 of a method/function inside the file myfile.m.

Having common field names specified centrally is a quite convenient way to autogenerate documentation. However, if you use e.g. the same parameter name in a different meaning and forget to explicitly specify the parameter documentation, the default values will be inserted. This possibly leads to more confusion for users than it does help. Furthermore, not specifiying the parameters in the local comments decreases readability of the code. One of mtoc++'s main advantages in combination with doxygen is that code can be commented highly readable in-place!

See the file itself for more detailed configuration options and examples.

Extending default LaTeX environment for doxygen

The latexextras.template file is processed and included into the latex environment available to doxygen during the documentation creation. Insert here any commands or packages that you want latex to know for your documentation formulas.

When having errors inside an LaTeX formula, doxygen will complain upon finishing and tell you to look into the _formulas.log/.tex file in the documentation output folder. THIS WARNING COMES ONLY ONE TIME! Upon the next creation run, only changed/new formulas will be re/generated. We considered deleting all formula pngs before each re-creation, but decided not to do this for performance issues. So just make sure you react to latex typos/errors immediately.

The default packages that are included by the latexextras.template are

* \usepackage{amssymb}
* \usepackage{amsfonts}
* \usepackage{subfig}
* \usepackage{bbm}

Fake classes for typical MatLab data types

The file class_substitutes.c includes some class descriptions for typical MatLab data types like handle or logical, but also introduces custom types like colvec or rowvec that can be used with the @type tag for property, parameter or return value types.

Add new classes to this file or change existing ones as you need.