Doxygen (1): 安装及设置

---

0. 前言

  使用 doxygen 的初心是在写 C++ 类视图的时候被多继承搞得很烦。doxygen 可以自动生成类继承关系图，此外还可以将规定格式的注释进行统一转换，对于后续学习使用代码以及自己理清代码大有帮助。
  专题目录如下:

• Doxygen (1): 安装及设置
• Doxygen (2): 部分设置
• Doxygen (3): 注释规范

  Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

  目前Doxygen可处理的程序语言包含：

• C/C++
• Java
• IDL (Corba, Microsoft及KDE-DCOP类型)

  而可产生出来的文档格式有：

• C/C++
• HTML
• XML
• LaTeX
• RTF
• Unix Man Page

  而其中还可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档。

1. 下载

链接：https://pan.baidu.com/s/1sxS4ovHKTLKhfRR7cSmNzA
提取码：spe0

  上述链接是我安装使用的三个安装包，我会把官网地址附在下面的软件简介中，想要下载最新版本的可以使用。(有过一次被和谐，已经更新。若仍被和谐请联系邮箱amorniss@qq.com)
  TIP：
  这都是我测试过的，安装没有问题(windows平台下)。
  为了发挥 Doxygen 的最大功效，需要搭配如下两款程序：

1.1 graphviz

  graphviz 是一个开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图。与UML类图类似。
  下载链接: http://www.graphviz.org/download/

1.2 Microsoft HTML Help Workshop

  这个工具用于生成CHM帮助文档，可读性较强。不过这个最新版本似乎被微软的其他程序给合并了，大家试试看吧。
  下载链接: https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads?redirectedfrom=MSDN

1.3 Doxygen

  不多说了。
  下载链接: https://www.doxygen.nl/download.html

2. 安装

略，全部都是一直next就行了。

3. 配置

运行安装目录下的 Doxywizard 开始配置

3.1 Wizard

3.1.1 Project

TIP：

• Doxygen 工作目录，就是用来存放配置文件的目录。
• 递归搜索源文件目录需要选上。

3.1.2 Mode

3.1.3 Output

3.1.4 Diagrams

TIP:
如果选择这个选项之前需要先安装了 Graphviz 工具包。

3.2 Expert

3.2.1 Project

TIP:

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

3.2.2 Build

TIP:

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

3.2.3 Input

TIP:
  输入的源文件的编码，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
  查看方法(以 VS 2019 为例)：
  文件 → 高级保存选项。此时如果这里还是选择UTF-8，那么会导致编译出来的CHM文件中的中文会有乱码。

3.2.4 HTML

TIP：

• 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 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

3.2.5 Dot

在Dot_PATH中填写GraphViz的安装路径。

3.3 保存配置信息

到上一步Doxygen已经完全配置好，可以在Run中点击运行了，但为了保存以上配置信息，可以将配置好的文件存一个.cfg文件，之后再运行 Doxygen 时只需要将该文件用Doxygen打开，改变第 3.1.1 中的输入、输出目录及工程的信息再运行。
File→Save as, 取一个名，默认为Doxyfile，加.cfg，点击保存。如果需要改变配置文件，改动之后再Save替换之前的配置文件即可。