步骤 0：检查 Doxygen 是否支持您的编程/硬件描述语言

首先，确保您的编程/硬件描述语言有合理的机会被 Doxygen 识别。默认情况下支持以下编程语言：C、C++、Lex、C#、Objective-C、IDL、Java、PHP、Python、Fortran 和 D。Doxygen 默认情况下还支持硬件描述语言 VHDL。可以配置某些文件类型扩展名以使用某些解析器：有关详细信息，请参阅配置/ExtensionMappings。此外，可以通过使用预处理器程序来支持完全不同的语言：有关详细信息，请参阅助手页面。

步骤 1：创建配置文件

Doxygen 使用配置文件来确定其所有设置。每个项目都应该有自己的配置文件。一个项目可以由一个源文件组成，但也可以是递归扫描的整个源树。

为了简化配置文件的创建，Doxygen 可以为您创建一个模板配置文件。为此，请从命令行使用 -g 选项调用 doxygen

doxygen -g <config-file>

其中 <config-file> 是配置文件的名称。如果省略文件名，将创建一个名为 Doxyfile 的文件。如果存在名为 <config-file> 的文件，Doxygen 将在生成配置模板之前将其重命名为 <config-file>.bak。如果使用 -（即减号）作为文件名，则 Doxygen 将尝试从标准输入 (stdin) 读取配置文件，这对于脚本编写非常有用。

配置文件的格式类似于（简单的）Makefile。它由许多形式为以下形式的赋值（标签）组成

TAGNAME = VALUE 或
TAGNAME = VALUE1 VALUE2 ...

您可能可以将生成的模板配置文件中大多数标签的值保留为其默认值。有关配置文件的更多详细信息，请参阅配置部分。

如果您不想使用文本编辑器编辑配置文件，则应查看 Doxywizard，它是一个 GUI 前端，可以创建、读取和写入 Doxygen 配置文件，并允许通过对话框输入设置配置选项。

对于由一些 C 和/或 C++ 源文件和头文件组成的小型项目，您可以将 INPUT 标签留空，Doxygen 将在当前目录中搜索源文件。

如果您有一个由源目录或树组成的大型项目，则应将根目录或目录分配给 INPUT 标签，并将一个或多个文件模式添加到 FILE_PATTERNS 标签（例如 *.cpp *.h）。只有与其中一种模式匹配的文件才会被解析（如果省略模式，则会使用 Doxygen 支持的文件类型的典型模式列表）。要递归解析源树，必须将 RECURSIVE 标签设置为 YES。为了进一步微调解析的文件列表，可以使用 EXCLUDE 和 EXCLUDE_PATTERNS 标签。例如，要从源树中省略所有 test 目录，可以使用

EXCLUDE_PATTERNS = */test/*

Doxygen 会查看文件的扩展名来确定如何解析文件，使用下表

扩展名	语言	扩展名	语言	扩展名	语言
.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

请注意，以上列表可能包含比默认情况下在 FILE_PATTERNS 中设置的更多项。

任何未解析的扩展名都可以通过将其添加到 FILE_PATTERNS 并设置适当的 EXTENSION_MAPPING 来设置。

如果您开始将 Doxygen 用于现有项目（因此没有任何 Doxygen 知道的文档），您仍然可以了解其结构以及文档化结果的外观。为此，您必须将配置文件中的 EXTRACT_ALL 标签设置为 YES。然后，Doxygen 将假装您的源代码中的所有内容都已记录。请注意，只要 EXTRACT_ALL 设置为 YES，就不会生成有关未记录成员的警告。

为了分析现有的软件，将（记录的）实体与其在源文件中的定义交叉引用非常有用。如果您将 SOURCE_BROWSER 标签设置为 YES，Doxygen 将生成此类交叉引用。它还可以通过将 INLINE_SOURCES 设置为 YES 将源代码直接包含在文档中（例如，这对于代码审查很有用）。

步骤 2：运行 Doxygen

要生成文档，您现在可以输入

doxygen <config-file>

根据您的设置，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 一样）。

HTML 输出

可以通过将 HTML 浏览器指向 html 目录中的 index.html 文件来查看生成的 HTML 文档。为了获得最佳结果，应使用支持层叠样式表 (CSS) 的浏览器（我使用 Mozilla Firefox、Google Chrome、Safari，有时还使用 IE8、IE9 和 Opera 来测试生成的输出）。

HTML 部分的某些功能（例如 GENERATE_TREEVIEW 或搜索引擎）需要支持动态 HTML 和启用 JavaScript 的浏览器。

LaTeX 输出

生成的 ${\LaTeX}$ 文档必须首先由 ${\LaTeX}$ 编译器编译（我使用最新的 teTeX 发行版（用于 Linux 和 macOS）和 MikTex（用于 Windows））。为了简化编译生成文档的过程，doxygen 会将 Makefile 写入 latex 目录（在 Windows 平台上也会生成 make.bat 批处理文件）。

Makefile 中的内容和目标取决于 USE_PDFLATEX 的设置。如果禁用（设置为 NO），则在 latex 目录中键入 make 将生成一个名为 refman.dvi 的 dvi 文件。然后可以使用 xdvi 查看此文件，或通过键入 make ps 将其转换为 PostScript 文件 refman.ps（这需要 dvips）。

要将 2 页放在一个物理页面上，请改用 make ps_2on1。可以将生成的 PostScript 文件发送到 PostScript 打印机。如果您没有 PostScript 打印机，可以尝试使用 ghostscript 将 PostScript 转换为您的打印机可以理解的格式。

如果您安装了 ghostscript 解释器，也可以转换为 PDF；只需键入 make pdf（或 make pdf_2on1）。

为了获得 PDF 输出的最佳效果，您应该将 PDF_HYPERLINKS 和 USE_PDFLATEX 标签设置为 YES。在这种情况下，Makefile 将仅包含直接构建 refman.pdf 的目标。

RTF 输出

Doxygen 将 RTF 输出合并到一个名为 refman.rtf 的文件中。此文件经过优化，可以导入到 Microsoft Word 中。某些信息使用所谓的字段进行编码。要显示实际值，您需要全选（编辑 - 全选），然后切换字段（右键单击并从下拉菜单中选择该选项）。

XML 输出

XML 输出包含 Doxygen 收集的信息的结构化“转储”。每个复合项（类/命名空间/文件/…）都有自己的 XML 文件，并且还有一个名为 index.xml 的索引文件。

还会生成一个名为 combine.xslt 的 XSLT 脚本，可用于将所有 XML 文件合并到一个文件中。

Doxygen 还会生成两个 XML 模式文件 index.xsd（用于索引文件）和 compound.xsd（用于复合文件）。此模式文件描述了可能的元素、它们的属性以及它们的结构方式，即它描述了 XML 文件的语法，可用于验证或指导 XSLT 脚本。

在 addon/doxmlparser 目录中，您可以找到一个解析器库，用于以增量方式读取 Doxygen 生成的 XML 输出（有关库的接口，请参见 addon/doxmlparser/doxmparser/index.py 和 addon/doxmlparser/doxmlparser/compound.py）。

Man 手册页输出

可以使用 man 程序查看生成的 man 手册页。您需要确保 man 目录在 man 路径中（请参见 MANPATH 环境变量）。请注意，man 手册页格式的功能存在一些限制，因此某些信息（如类图、交叉引用和公式）将会丢失。

DocBook 输出

Doxygen 还可以生成 DocBook 格式的输出。如何处理 DocBook 输出超出了本手册的范围。

步骤 3：编写源代码文档

尽管编写源代码文档被视为步骤 3，但在新项目中，这当然应该是步骤 1。这里我假设您已经有一些代码，并且您希望 Doxygen 生成一个漂亮的文档，描述 API，可能还有内部结构和一些相关的设计文档。

如果在配置文件中将 EXTRACT_ALL 选项设置为 NO（默认值），则 Doxygen 将仅为已记录的实体生成文档。那么，如何记录这些内容呢？对于成员、类和命名空间，基本上有两种选择：

在成员、类或命名空间的声明或定义之前放置一个特殊的文档块。对于文件、类和命名空间成员，也允许将文档直接放置在成员之后。

请参阅特殊注释块部分，了解有关特殊文档块的更多信息。
在其他位置（另一个文件或其他位置）放置一个特殊的文档块，并在文档块中放置一个结构命令。结构命令将文档块链接到可以记录的特定实体（例如，成员、类、命名空间或文件）。

请参阅其他位置的文档部分，了解有关结构命令的更多信息。

第一种方法的优点是您不必重复实体的名称。

只能使用第二种方法来记录文件，因为没有办法在文件之前放置文档块。当然，文件成员（函数、变量、typedef、define）不需要显式的结构命令；只需在它们之前或之后放置一个特殊的文档块即可。

特殊文档块内的文本在写入 HTML 和/或 ${\LaTeX}$ 输出文件之前会被解析。

在解析过程中，会执行以下步骤：

Markdown 格式会被替换为相应的 HTML 或特殊命令。
文档内的特殊命令会被执行。请参阅特殊命令部分，了解所有命令的概述。
如果一行以一些空格开头，后跟一个或多个星号 (*)，然后可以选择更多空格，则所有空格和星号都会被删除。
所有生成的空行都被视为段落分隔符。这可以避免您自己放置新段落命令，以使生成的文档可读。
为与已记录的类对应的单词创建链接（除非该单词前面带有 %；在这种情况下，该单词不会被链接，并且 % 符号会被删除）。
当在文本中找到某些模式时，会创建指向成员的链接。请参阅自动链接生成部分，了解有关自动链接生成工作原理的更多信息。
文档中的 HTML 标签会被解释并转换为 ${\LaTeX}$ 输出的 ${\LaTeX}$ 等效项。请参阅 HTML 命令部分，了解所有受支持的 HTML 标签的概述。

转到下一节或返回索引。