原文地址：https://doxygen.nl/manual/starting.html

入门

可执行文件doxygen是解析源代码并生成文档的主程序。有关使用的更详细信息，请参阅 Doxygen usage。

另外，你也可以选择使用 doxywizard ，它是一个图形前端。它可以编辑 doxygen 使用的配置文件，并在图形环境中运行 doxygen。对于 Mac OS X doxywizard 将通过单击 doxygen 应用程序图标来启动。

下图显示了工具之间的关系，以及它们之间的数据流动情况（看起来很复杂，但这只是因为它想把所有信息都表示出来）：

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

首先，确保您的编程/硬件描述语言会被 doxygen 识别。

默认状态下，以下编程语言是支持的：C、C++、Lex、C#、Objective-C、IDL、Java、PHP、Python、Fortran 和 D。Doxygen 默认还支持硬件描述语言 VHDL。

你还可以配置针对特定文件类型扩展名使用特定解析器（详见 Configuration/ExtensionMappings）。此外，使用预处理程序可以支持完全不同的语言（详见 Helpers page）。

步骤 1：创建配置文件

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

为了简化配置文件的创建，doxygen 可以为你创建一个模板配置文件。要想这么做，可以用-g的参数在命令行执行doxygen：

doxygen -g <config-file>

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

配置文件的格式类似于一个简化的Makefile。它由许多 assignments（tags，标签）以下面的形式组成：
TAGNAME = VALUE
或者
TAGNAME = VALUE1 VALUE2 ...

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

如果你不想用文本编辑器编辑配置文件，你应该看看doxywizard，它是一个图形界面前端，可以创建、读取和写入 doxygen配置文件，并允许通过对话框来输入配置选项。

对于由几个 C或 C++ 源文件和头文件组成的小项目，您可以将 INPUT标签留空，doxygen 将在当前目录中搜索源代码。

如果您有一个包含源目录或树的较大项目，您应该将根目录或目录分配给INPUT标记，并将一个或多个文件格式添加到FILE_PATTERNS标记（例如*.cpp *.h）。只有匹配的文件才会被解析（如果省略格式，一个标准的 doxygen 支持格式列表将会被使用）。对于源代码树的递归解析，您必须将RECURSIVE标记设置为YES. 要进一步微调解析的文件列表，可以使用EXCLUDE和EXCLUDE_PATTERNS标签。例如，要从源代码树中省略所有test目录，可以使用：

EXCLUDE_PATTERNS = */test/*

Doxygen 使用下表来确定特定文件扩展名将以什么语言来解析：

请注意，上面的列表可能包含比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、$\text{LATEX}$、XML、Unix 手册页和 DocBook 格式的文档。

默认输出目录是doxygen启动的目录。可以使用OUTPUT_DIRECTORY更改输出的根目录。可以使用HTML_OUTPUT、RTF_OUTPUT、LATEX_OUTPUT、XML_OUTPUT、MAN_OUTPUT和DOCBOOK_OUTPUT选择输出目录中的格式特定目录。如果输出目录不存在，doxygen将尝试为您创建它（但它不会像mkdir -p那样递归地创建整个路径）。

HTML 输出

可以用浏览器打开html目录中的index.html来查看生成的 HTML 文档。为看到最佳效果，应使用CSS(cascading style sheets) 的浏览器（我使用 Mozilla Firefox、Google Chrome、Safari，有时还使用 IE8、IE9 和 Opera 来测试）。

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

$\text{LATEX}$输出

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

Makefile中的内容和 targets 取决于USE_PDFLATEX的设置。如果它被禁用（设置为NO），则在latex目录中键入make会生成一个名为refman.dvi的dvi文件。这个文件可以用xdvi来浏览，或者键入make ps（需要有dvips）来将这个文件转换为一个名为refman.ps的 PostScript 文件。

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

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

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

RTF 输出

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

XML 输出

XML输出由 doxygen 收集的信息结构化“转存”组成。每个 compound（类/命名空间/文件/…）都有自己的 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 page输出

生成的 Man page 可以使用man程序查看。您确实需要确保 man 目录位于 man 路径中（请检查MANPATH环境变量）。请注意，man page的功能存在一些限制，因此某些信息（如类图、对照和公式）将会丢失。

DocBook 输出

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

步骤 3：源代码的注释文档

尽管这写在了“步骤3”，但在一个新项目中，这当然应该是第 1 步。在这里，我假设您已经有一些代码，并且您希望 doxygen 生成一个美观的文档来描述 API，可能还有内部和一些相关的设计。

如果在配置文件中将EXTRACT_ALL选项设置为NO（默认情况），那么 doxygen 将只为有注释文档的实体生成文档。那么如何写注释文档呢？对于成员、类和命名空间，基本上有两种选择：

1. 在成员、类或命名空间的声明或定义之前放置一个 特殊的 注释文档块。对于文件、类和命名空间成员，也允许将注释文档直接放在成员之后。请阅读 特殊的注释文档块 来了解更多信息。
2. 在其他地方（另一个文件或另一个位置）放置一个特殊的文档块，并且在文档块中放置一个结构化的命令。结构化命令将文档块链接到可以记录的特定实体（例如，成员、类、名称空间或文件）。请阅读 在其他地方的注释文档 来了解更多信息。

第 1 个方式的优点是您不必重复写实体的名称。

“文件”只能使用第 2 个方式，因为显然无法在“文件”之前放置文档块。当然，文件成员（函数、变量、类型定义、定义）只需在它们前面或后面放置一个特殊的文档块就可以了。

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

在解析过程中会发生以下步骤：

• Markdown 格式被相应的 HTML 或特殊命令替换。
• 文档中的特殊命令会被执行。有关所有命令的概述，请参阅 特殊命令 。
• 如果一行以一些空格开头，后跟一个或多个星号 ( *)，或是更多空格，则删除所有空格和星号。
• 所有生成的空行都被视为段落分隔符。这使您不必自己放置 new-paragraph 命令以使生成的文档具有可读性。
• 为对应于文档的词语创建链接（除非该词语前面有一个 %；那么该词语将不会被链接并且 % 符号被删除）。
• 当在文本中找到某些格式时，会创建指向成员的链接。有关自动链接生成如何工作的更多信息，请参阅 自动链接生成 。
• 文档中的 HTML 标记被解释并转换为等效的 $\text{LATEX}$ 以用于 $\text{LATEX}$ 输出。有关所有受支持的 HTML 标记的概述，请参阅 HTML 命令。