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

首先，确保您的编程/硬件描述语言有很大可能被 Doxygen 识别。默认支持以下编程语言：C、C++、Lex、C#、Objective-C、IDL、Java、PHP、Python、Fortran 和 D。Doxygen 默认也支持硬件描述语言 VHDL。可以配置某些文件类型扩展名以使用特定的解析器：详情请参见配置/扩展映射。此外，可以通过使用预处理器程序支持完全不同的语言：详情请参见助手页面。

步骤 1：创建配置文件

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

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

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 手册页和 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 会在 latex 目录中写入一个 Makefile（在 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 路径中（请参阅 MANPATH 环境变量）。请注意，手册页格式的功能存在一些限制，因此某些信息（如类图、交叉引用和公式）将会丢失。

DocBook 输出

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

步骤 3：文档化源代码

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

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

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

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

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

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

文件只能使用第二种选择进行文档化，因为无法在文件之前放置文档块。当然，文件成员（函数、变量、typedef、defines）不需要显式的结构化命令；只需将特殊的文档块放在它们前面或后面即可。

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

解析期间会发生以下步骤

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

转到下一部分或返回索引。