MLi's Blog

mtoc++创建matlab代码文档

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, 解压缩以后为:

1
2
3
4
5
6
├─tools
│ └─config
├─win32
│ └─debug
└─win64
└─debug

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

matlab项目里配置mtoc++

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

1
└─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文件夹)

    设置完提示安装成功

    1
    2
    3
    4
    5
    6
    [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,注释如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
% 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