mtoc++是什么

mtoc++是matlab的doxygen的语法过滤器，能够生成代码文档。

The filter program ‘mtocpp’ transforms relevant parts of the M-Files into C++ syntax, which can be parsed by doxygen. The generated html files can be processed by the program ‘mtocpp_post’ in order to generate documentation looking more like Matlab.

Short mtoc++ feature list:

Transforms function m-files into standalone functions
Supports most of the OOP features from Matlab

mtoc++安装

在mtoc++之前首先需要安装Doxygen(必选，1.8版本以后的)和dot graphviz软件(可选，用于生成程序之间的图结构)。

安装完以后将上面两个软件的bin目录加到系统环境变量中，比如：

C:\Program Files (x86)\Graphviz2.38\bin

接下来需要下载mtoc++, 我用的是windows64位系统，直接下载的是编译好的Windows binaries (32/64bit) and tools，解压缩以后为：

├─tools
│  └─config
├─win32
│  └─debug
└─win64
    └─debug

将win64文件添加到系统环境变量。

matlab项目里配置mtoc++

我在本地创建了个matlab测试project为testMtocpp(已上传至github仓库)：

└─src

其中src里为测试的matlab文件。

将mtoc++/tools下的MatlabDocMaker.m文件拷贝到src目录下
打开MatlabDocMaker.m，将function name = getProjectName下的error注释掉，并设置项目名，比如：
1
name = 'My mtoc++ test project';
将mtoc++/tools下的config拷贝到src的同级目录下
在src的同级目录下新建doc文件夹，最后的结构为

1
2
3

├─config
├─doc
└─src

运行MatlabDocMaker生成文档

在matlab命令窗口输入：MatlabDocMaker.setup, 按照提示设置

1
2
3

your projects source directory (输入n，然后选择src)
documentation configuration files directory (选config文件夹)
documentation output directory (选doc文件夹)

设置完提示安装成功

[Required] Checking for doxygen...  found 1.8.13
[Required] Checking for mtoc++...  found 1.5
[Recommended] Checking for dot...  found dot - graphviz version 2.38.0 (20140413.2041)
[Recommended] Checking for latex...  found MiKTeX-pdfTeX 2.9.4307 (1.40.12) (MiKTeX 2.9)
[Recommended] Checking for ghostscript...  found 9.05
<<<< MatlabDocMaker setup successful. >>>>

运行MatlabDocMaker.create生成文档

进阶学习

设置中文comment

函数的简单注释

源程序为simpleCommentDemo.m，注释如下:

% This is a simple demo of function comments for mtoc++ (brief description)
%
% Detailed description:
% This is detailed description (After the first empty documentation line, paragraphs of the detailed
% description begin)
%
% see: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#docstructure
%
% also see: http://mdengli.com/mtocppLearn/ for a detail explaination
%
% for a complicated demo of function comments, please see doxygen.m  @see doxygen.m
% Parameters:
%  len: first parameter of type double.
%
% Return values:
%  y: return value
%
% Required fields of len:
%  test: Description for required field len.test
%| \todo There needs to be done something in this file
% \note this is note
% \version 0.1
% \author Matthew Li
% \email mdeng1985@gmail.com
% \date Feb-03-2017
% \copyright GNU Public License.

生成网页以后是

几点解读：

注释分为两部分：第一部分为description, parameters, return values；第二部分为doxygen直接支持的命令
连接第一部分和第二部分要有个空行，这个空行开头不能有%
第一部分内部和第二部分内部：如果中间是空行，开头必须要有%，否则参数的注释会失效。
第二部分的执行doxygen命令的时候，要以%|开头。
第二部分常见的doxygen命令为\author, \todo。好像@命令和\命令的含义是一样的。更多doxygen命令为： doxygen commands, 比如
段落的第一行已冒号结尾，这样这一行就会以黑体显示
可以直接引用m文件，比如引用demo.m直接输入demo.m

函数注释全解读

详细的示例文件：doxygen.m