Doxygen使用教程1--安装配置

Doxygen简介

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。
Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。

目前Doxygen支持程序语言包括：C++、C++/CLI、Java、C#、C、PHP、Fortran、VHDL……
可产生的文档格式：HTML、XML、LaTeX、RTF、Unix Man Page……
而其中还可衍生出不少其他格式。如HTML可以打包成CHM格式，LaTeX可通过工具生成PS或PDF文档等。

Doxygen及相关工具的安装

1. 安装Doxygen：http://www.doxygen.nl/download.html
2. 安装Graphviz：https://graphviz.gitlab.io/_pages/Download/Download_windows.html
   graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。
3. 安装Windows Help Workshop：https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads
   Doxygen 使用这个工具可以生成 CHM 格式的文档。

Doxygen配置

Doxygen 产生文档可以分为三个步骤。

1. 在程序代码中加上符合Doxygen所定义批注格式。后续会详细说明。
2. 使用Doxywizard进行配置。
3. 三是使用Doxygen来产生批注文档。

Doxygen主界面

Wizard标签下的Mode

Wizard标签下的Output

Wizard标签下的Diagrams

备注：如果选择“用Graphviz来生成类图”选项之前需要先安装了 Graphviz 工具包。

Expert标签下的Project

备注：

• 编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.
• TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
• OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。
• SUBGROUPING 这个选项选择后，输出将会按类型分组。

Expert标签下的Build

Build页面，这个页面是生成帮助信息中比较关键的配置页面：

• EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。
• EXTRACT_PRIVATE 表示：输出private函数。
• EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。
• HIDE_UNDOC_MEMBERS 表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
• INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。
• CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议永远不要开启。
• HIDE_SCOPE_NAMES 表示：域隐藏，建议永远不要开启。
• SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
• INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
• SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
• GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。
• SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
• SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

expert 标签下的 HTML Topics

备注：

• CHM_FILE文件名需要加上后缀（xx.chm）；
• 如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。
• 为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。
• GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
• TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

expert 标签下的 Dot

Run 标签