开发框架07- Doxygen 文档生成

type

date

slug

参考资料

Doxygen: Installation （环境安装参考）

Doxygen: Getting started（快速上手）

Doxygen: Documenting the code（代码注释）

Doxygen 和代码文档 - 功能 | CLion

Doxygen documentation | CLion Documentation

Doxygen: Customizing the output（定义HTML文档样式，调整导航栏和breadcrumb导航条位置）

Doxygen: Searching（添加文档搜索功能）

Doxygen: Emoji support（添加表情支持）

Doxygen: Markdown support（Markdown支持）

Doxygen: Grouping（Group功能）

Doxygen快速入门 - 知乎

环境安装

下载安装 GraphViz，推荐版本 2.38 以上，Doxygen 使用GraphViz dot 工具优化图效果

若要生成 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 通过一个配置文件确定所有设置，每个项目需有对应配置文件。对于 doxygen 项目来说，既可以是一个文件，也可以是整个文件树，可以递归扫描。

-g 生成默认配置模板

<config-file> 用户指定名称。若未指定，文件名称默认为Doxyfile，假如同名配置文件已存在，doxygen 在生成前，会将源文件备份，重命名为<config-file>.bak。

<config-file> 为 “-”时，配置通过命令行输入

Doxygen Wizard 图形界面中选项位置

INPUT 标签

指定需要生成文档的文件或文件夹，可多选，通过空格分隔。若标签是空，则会使用当前文件夹。

FILE_PATTERNS 标签

使用通配符过滤INPUT 指定文件夹，支持的文件格式如下，若不在支持之列，需通过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 标签

打开此开关，则会生成一个源文件列表。文档中的实体将与这些源文件进行交叉引用。

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 浏览器指向 html 目录中的 index.html 文件来查看。为了获得最佳效果，建议使用支持层叠样式表（CSS）的浏览器比如 Mozilla Firefox、Google Chrome、Safari，有时还使用 IE8、IE9 和 Opera 来测试生成的输出）。

Latex 输出

生成的Latex 文档必须首先由 Latex 编译器编译（我使用最近的 teTeX 发行版用于 Linux 和 macOS，使用 MikTex 用于 Windows）。为了简化生成文档的编译过程， 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，将自动添加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

有是那种机制实现文档组合，第一种叫做“Topics”，第二种叫做“member groups”，对于页面，还存在“Subpaging”机制。

Topics

Grouping 是将分散页面通过主题组织起来，呈现出新的页面。主题方式组织的成员可以是文件、命名空间、类、概念、模块、函数、变量、枚举、宏定义等，也可以嵌套组。

相关的定义有这些 \ingroup, \defgroup, \addtogroup, \weakgroup（可以点进去查看具体说明），根据优先级从高到低排序。

\ingroup 添加成员

\defgroup 定义组

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

Doxygen 将把成员放入具有最高“优先级”的组中：例如，显式的 \ingroup 会覆盖通过 @{ @} 的隐式分组定义。具有相同优先级的冲突分组定义会触发警告，除非是针对没有任何显式文档的成员。以下示例将 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.