开发框架07- Doxygen 文档生成

若要生成 HTML 文件，需要下载微软的 HTML 帮助工具。2021 年初，微软下线了包含下载链接的原始页面，因此可从网络档案中下载安装文件，或参考 Download Microsoft HTML Help Workshop (HTML Help or CHM compiler, HHC.EXE)

若要生成支持科学公式的 PDF 文件，需要安装 LaTeX 和 Ghostscript.

Ghostscript 从官网下载
LaTex有诸多发布版，推荐 MikTex and proTeXt
两者安装完成后，需要添加到系统环境变量。添加后，可在终端中输入 latex.exe、pdflatex.exe 和 gswin32c.exe（或 gswin64c.exe）进行验证。

从官方链接下载 Doxygen。

快速上手

步骤1 创建配置文件

Doxygen 通过配置文件管理全部设置。每个项目通常都需要一份独立的配置文件；项目输入既可以是单个文件，也可以是完整的文件树，并支持递归扫描。

-g：生成默认配置模板。

\<config-file\>：用户指定的配置文件名。若未指定，默认文件名为 Doxyfile。如果同名配置文件已存在，Doxygen 会先备份原文件，并将其重命名为 \<config-file\>.bak。

当 \<config-file\> 为 - 时，配置将通过命令行输入。

Doxygen Wizard 图形界面中的选项位置如下：

INPUT 标签

用于指定需要生成文档的文件或文件夹。可填写多个路径，并使用空格分隔；若该标签为空，则默认使用当前文件夹。

FILE_PATTERNS 标签

用于通过通配符过滤 INPUT 指定目录中的文件。Doxygen 支持的文件格式如下；若文件扩展名不在支持列表中，需要通过 EXTENSION_MAPPING 额外配置，否则 Doxygen 不会读取该文件。

Extension	Language	Extension	Language	Extension	Language
.dox	C / C++	.HH	C / C++	.py	Python
.doc	C / C++	.hxx	C / C++	.pyw	Python
.c	C / C++	.hpp	C / C++	.f	Fortran
.cc	C / C++	.h++	C / C++	.for	Fortran
.cxx	C / C++	.mm	C / C++	.f90	Fortran
.cpp	C / C++	.txt	C / C++	.f95	Fortran
.c++	C / C++	.idl	IDL	.f03	Fortran
.cppm	C / C++	.ddl	IDL	.f08	Fortran
.ccm	C / C++	.odl	IDL	.f18	Fortran
.cxxm	C / C++	.java	Java	.vhd	VHDL
.c++m	C / C++	.cs	C#	.vhdl	VHDL
.ii	C / C++	.d	D	.ucf	VHDL
.ixx	C / C++	.php	PHP	.qsf	VHDL
.ipp	C / C++	.php4	PHP	.l	Lex
.i++	C / C++	.php5	PHP	.md	Markdown
.inl	C / C++	.inc	PHP	.markdown	Markdown
.h	C / C++	.phtml	PHP	.ice	Slice
.H	C / C++	.m	Objective-C
.hh	C / C++	.M	Objective-C

RECURSIVE 标签

用于控制是否递归搜索 INPUT 指定目录下的子目录。

EXCLUDE 和 EXCLUDE_PATTERNS 标签

EXCLUDE 用于排除指定的文件或文件夹；EXCLUDE_PATTERNS 则通过通配符批量排除。比如，下面的配置会排除所有 test 文件夹。

SOURCE_BROWSER 标签

开启该选项后，Doxygen 会生成源文件列表，文档中的实体也会与源文件建立交叉引用。

INLINE_SOURCES 标签

将 INLINE_SOURCES 设置为 YES 后，函数体、多行宏、枚举或列表初始化变量的内容会直接包含在生成的文档中。

步骤2 运行Doxygen

根据配置不同，Doxygen 会在输出目录中创建 html、rtf、latex、xml、man 和/或 docbook 等目录。顾名思义，这些目录分别保存 HTML、RTF、LaTeX、XML、Unix man 页面和 DocBook 格式的文档。

默认输出目录是 Doxygen 启动时所在的目录。可以通过 OUTPUT_DIRECTORY 修改输出根目录，也可以通过配置文件中的 HTML_OUTPUT、RTF_OUTPUT、LATEX_OUTPUT、XML_OUTPUT、MAN_OUTPUT 和 DOCBOOK_OUTPUT 指定不同格式的子目录。若输出目录不存在，Doxygen 会尝试自动创建，但不会像 mkdir -p 那样递归创建完整路径。

OUTPUT_DIRECTORY 标签

用于指定文档输出路径。若填写相对路径，则该路径相对于 Doxygen 启动目录；若留空，则默认使用当前目录。

HTML 输出

生成的 HTML 文档可通过浏览器打开 html 目录下的 index.html 查看。为了获得更好的显示效果，建议使用支持 CSS 的现代浏览器，例如 Mozilla Firefox、Google Chrome 或 Safari。

Latex 输出

生成的 LaTeX 文档需要先通过 LaTeX 编译器编译。为了简化编译流程，Doxygen 会在 latex 目录中生成一个 Makefile；在 Windows 平台上，还会额外生成 make.bat 批处理文件。

安装 Ghostscript 解释器后，只需执行 make pdf 即可将文档转换为 PDF。

为了获得更好的 PDF 输出效果，建议将 PDF_HYPERLINKS 和 USE_PDFLATEX 设置为 YES。此时，Makefile 通常会直接构建 refman.pdf。

如何注释（C/C++）

高质量注释是生成高质量文档的前提。对于成员、类和命名空间等实体，通常有两种记录方式：

选项1：就近添加注释块

在声明或定义前添加特殊注释块。对于文件、类和命名空间成员，也可以将文档直接放在成员之后。

选项2：添加结构命令

这种方式更灵活：通过在注释块中添加特殊结构命令，将注释块与目标实体显式关联。

第一种方式的优点是无需重复实体名称。

文件只能通过第二种方式进行文档化，因为不存在“放在文件之前”的注释位置。当然，文件成员（函数、变量、类型定义、宏定义）通常不需要显式结构命令，只需在其前面或后面放置特殊文档块即可。

Comment blocks for C-like languages

C-style comment block

Qt style and add an exclamation mark (!)

Multi-line special C++ comments

Banner Comment

Click here for the corresponding HTML documentation that is generated by Doxygen.

⚠️

与大多数文档系统不同，Doxygen 允许将成员（包括全局函数）的文档放在定义之前。这样，详细说明可以保留在源文件中，而不是挤进头文件；头文件更紧凑，成员实现者也能更方便地维护文档。折中做法是：在声明前放简要描述，在成员定义前放详细描述。

Brief 描述通常有以下几种写法：

添加 \\brief 命令，空行之后再写详细描述。

将 JAVADOC_AUTOBRIEF 设置为 YES 后，Doxygen 会自动将第一个英文句点 . 之前的内容识别为 brief 描述，其后的内容作为详细描述。该方式适用于 Javadoc 风格注释和 C++ 多行注释。

第三种方式是使用一种特殊的 C++ 风格单行注释。下面是两个示例：

注意最后一个示例中的空行：它用于将简要描述与详细描述分开。在这种情况下，JAVADOC_AUTOBRIEF 也应设置为 NO。

Putting documentation after members

在记录文件、结构体、联合体、类或枚举成员时，有时希望将文档块放在成员之后，而不是成员之前。此时需要在注释块中额外添加一个 \< 标记。该规则同样适用于函数参数。

下面是这些注释块的使用示例：

Click here for the corresponding HTML documentation that is generated by Doxygen. 以下是一个使用 Qt 风格的 C++代码文档示例：

Click here for the corresponding HTML documentation that is generated by Doxygen. 简要描述包含在类、命名空间或文件的成员概述中，并使用小号斜体字体打印（通过在配置文件中将 BRIEF_MEMBER_DESC 设置为 NO 可以隐藏此描述）。默认情况下，简要描述成为详细描述的第一句话（但可以通过将 REPEAT_BRIEF 标签设置为 NO 来更改）。对于 Qt 风格，简要描述和详细描述都是可选的。

默认情况下，Javadoc 风格的文档块与 Qt 风格的文档块表现相同。然而，这并不符合 Javadoc 规范，在该规范中，文档块的第一句话会自动被视为简要描述。要启用此行为，您应该在配置文件中将 JAVADOC_AUTOBRIEF 设置为 YES。如果您启用此选项并希望在句子中间放置句点而不结束该句子，您应在其后放置反斜杠和空格。以下是一个示例：

Click here for the corresponding HTML documentation that is generated by Doxygen.

Documentation at other places

在上一节示例中，注释块通常位于文件、类或命名空间的声明/定义之前，或者位于成员之前/之后。大多数情况下这样最方便，但某些场景下也需要把文档放在其他位置。对于文件文档来说，这甚至是必要的，因为不存在真正意义上的“文件前面”。

Doxygen 几乎允许将文档块放在任何位置，例外是函数体内部和普通 C 风格注释块内部。

如果文档块没有直接放在目标实体之前或之后，就需要在注释块中使用结构命令显式关联实体，这会带来一定的信息重复。因此在实践中，除非确有必要，否则应尽量避免过度使用结构命令。

\struct to document a C-struct.

\union to document a union.

\enum to document an enumeration type.

\fn to document a function.

\var to document a variable or typedef or enum value.

\def to document a #define.

\typedef to document a type definition.

\file to document a file.

\namespace to document a namespace.

\package to document a Java package.

\interface to document an IDL interface.

Click here for the corresponding HTML documentation that is generated by Doxygen.

Grouping

Grouping 主要提供三种文档组织机制：第一种是 “Topics”，第二种是 “Member Groups”，对于页面还可以使用 “Subpaging” 机制。

Topics

Grouping 用于按主题组织分散的文档内容，并生成新的主题页面。主题组可以包含文件、命名空间、类、概念、模块、函数、变量、枚举、宏定义等，也可以继续嵌套子组。

相关命令包括 \ingroup、\defgroup、\addtogroup、\weakgroup（可点击查看具体说明），下面按优先级从高到低说明：

\\ingroup：将成员加入指定组。

\\defgroup：定义一个组。

\\addtogroup：可用于替代 \\defgroup。如果组标签不唯一，它会自动合并文档；而 \\defgroup 会产生错误消息。

Doxygen 会将成员放入最高优先级的组中。例如，显式的 \\ingroup 会覆盖通过 @{ @} 定义的隐式分组。若相同优先级的分组定义发生冲突，通常会触发警告；但如果冲突对象没有任何显式文档，Doxygen 可能会静默处理。以下示例将 VarInA 放入组 A，并将 IntegerVariable 放入 IntVariables，从而静默解决冲突，因为 IntegerVariable 的第二个实例没有文档记录。

再来看一个例子

Click here for the corresponding HTML documentation that is generated by Doxygen.

Member Groups

如果一个复合体（例如类或文件）包含大量成员，通常需要进一步分组。Doxygen 会根据类型和访问级别自动分组，但默认分组未必符合阅读需求，因此可以使用成员组方式自定义组织结构。

在块的起始标记之前，可以放置一个单独的注释块。该注释块应包含 @name（或 \\name）命令，用于指定组标题；也可以进一步补充该组的详细说明。

如果类内某个成员组中的所有成员具有相同类型和访问级别（例如全部是静态公共成员），则该成员组会作为对应类型/访问级别分组下的子组显示，例如作为“静态公共成员”部分的子章节。如果成员类型不同，则该组会与自动生成的分组处于同一级别。若希望强制类内所有成员组都位于顶级，可在类文档中添加 \\nosubgrouping 命令。

Click here for the corresponding HTML documentation that is generated by Doxygen.