使用 Doxygen 在 Linux 上为您的源代码编写文档

这个广泛使用的开源工具可以从您的注释中生成文档。

图片来源：

Internet Archive Book Images。由 Opensource.com 修改。CC BY-SA 4.0

当您尝试熟悉别人的项目时，您通常会感激他们留下的注释，这些注释可以帮助您理解他们代码的含义。同样地，无论您是为自己还是为他人编程，注释自己的代码都是一个好习惯。所有编程语言都提供特殊的语法来标记一个单词、一行或整个部分作为注释。当处理源代码时，编译器或解释器会忽略这些区域。

注释不能代替文档，但有一种方法可以使用您的注释轻松生成文档。认识一下 Doxygen，这是一个开源工具，用于根据代码中的注释生成 HTML 或 LaTeX 文档。Doxygen 使您能够全面了解代码的结构，而无需额外的努力。虽然 Doxygen 主要用于记录 C++，但您也可以将其用于许多其他语言，如 C、Objective-C、C#、PHP、Java、Python 等。

要使用 Doxygen，您只需以 Doxygen 可以读取的语法注释您的源代码。然后 Doxygen 会遍历您的源文件，并根据这些特殊注释创建 HTML 或 LaTeX 文档。下面的 C++ 示例项目将说明如何注释源代码以及如何从中生成文档。该示例可在 GitHub 上找到，我还会引用 Doxygen 手册和文档的不同部分。

[ 立即下载：Doxygen 速查表 ]

在 Linux 上安装 Doxygen

在 Fedora 上，Doxygen 可以作为一个软件包使用。打开终端并运行

sudo dnf install doxygen

在基于 Debian 的系统上，您可以通过运行以下命令安装它

sudo apt-get install doxygen

用法

安装完成后，您只需要一个带有 Doxygen 兼容注释的项目和一个 Doxyfile，这是一个控制 Doxygen 行为的配置文件。

注意：如果您坚持使用 GitHub 上的相关示例项目，您可以省略下一步。

如果还没有 Doxyfile，您可以简单地让 Doxygen 生成一个标准模板。为此，导航到您的项目根目录并运行

doxygen -g

-g 代表生成。您现在应该注意到一个新创建的文件名为 Doxyfile。您可以通过简单地运行以下命令来调用 Doxygen

doxygen

您现在应该注意到两个新创建的文件夹

html/
latex/

默认情况下，Doxygen 输出 LaTeX 格式的文档以及基于 HTML 的文档。在本文中，我将只关注基于 HTML 的文档。您可以在官方 Doxygen 文档的入门部分找到有关 LaTeX 输出的更多信息。

双击 html/index.html 以打开实际的 HTML 文档。使用空白配置，它可能看起来像下面的屏幕截图

A screenshot of a doxygen generated main page on Firefox. The content field under My Project Documentation is blank.

图片来源：

(Stephan Avenwedde，CC BY-SA 4.0)

现在是修改 Doxyfile 并在源代码中添加一些特殊注释的时候了。

更多 Linux 资源

Doxyfile

Doxyfile 允许您定义大量的调整可能性，所以我将只描述一个非常小的子集。这些设置对应于示例项目的 Doxyfile。

第 35 行：项目名称

在这里您可以指定项目名称，它将在标题行和浏览器选项卡中可见。

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
# double-quotes, unless you are using Doxywizard) that should identify the
# project for which the documentation is generated. This name is used in the
# title of most generated pages and in a few other places.
# The default value is: My Project.

PROJECT_NAME           = "My Project"

第 47 行：项目简短描述

简短描述也将显示在标题中，但字体较小。

# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.

PROJECT_BRIEF          = "An example of using Doxygen in C++"

第 926 行：包含子目录

允许 Doxygen 递归地遍历子目录以查找源文件和文档文件。

# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
# The default value is: NO.

RECURSIVE = YES

第 1769 行：禁用 LaTeX 输出

如果您只对 HTML 输出感兴趣，您可以使用此开关禁用 LaTeX 代码生成。

# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.

# The default value is: YES.

GENERATE_LATEX = NO

每次更改后，您可以再次运行 Doxygen 以检查您的更改是否产生了预期的效果。如果您只想检查现有 Doxyfile 有哪些修改，请使用 -x 开关调用 Doxygen

A screenshot of the terminal showing the differences, Project Name, Project Brief, Recursive, and status of Generate Latex

图片来源：

(Stephan Avenwedde，CC BY-SA 4.0)

与命令 diff 一样，Doxygen 只显示实际 Doxyfile 和模板之间的差异。

特殊注释

Doxygen 读取源文件并检查每个文件的特殊注释。基于这些注释和关键字，它构建 HTML 文档。特殊注释的结构可以使用类 ByteStream 的头文件很好地解释，如上面链接的 GitHub 示例所示。

我将以构造函数和析构函数为例进行说明

/*! @brief Constructor which takes an external buffer to operate on
*
* The specified buffer already exist.
* Memory and size can be accessed by buffer() and size().
*
* @param[in] pBuf Pointer to existing buffer
* @param[in] size Size of the existing buffer
*/

ByteStream(char* pBuf, size_t size) noexcept;

格式化特殊注释块有不同的风格。我更喜欢以 Qt 风格 (/*!) 开始注释，并在每行之前添加星号 (*)。然后该块以星号后跟正斜杠 (*/) 结束。要了解不同风格选项的概述，请参阅 Doxygen 手册中的文档代码部分。

Doxygen 中的注释分为两个部分：简要描述和详细描述。这两个部分都是可选的。在上面的代码示例中，注释块引用了以下代码行，即构造函数的声明。@brief 后面的句子将显示在紧凑的类概述中

A screenshot of the C++ example of using Doxygen showing the Byte Stream Class Reference. The categories in the list are public member functions, writing (operators for writing to the stream), and reading (operators for reading from the stream)

图片来源：

(Stephan Avenwedde，CC BY-SA 4.0)

在空行之后（空行被视为段落分隔符），构造函数的实际文档开始。使用 @param[in/out] 关键字，您可以标记传递给构造函数的参数，Doxygen 将从中创建一个清晰的参数列表

Screenshot of the Doxygen example showing the parameters under ByteStream

图片来源：

(Stephan Avenwedde，CC BY-SA 4.0)

请注意，Doxygen 会自动创建指向注释中提到的 buffer() 和 size() 方法的链接。相反，析构函数声明之前的注释不会对 Doxygen 产生任何影响，因为它不被识别为特殊注释

// Destructor
~ByteStream();

现在您已经了解了 90% 的魔法。通过对注释使用稍微修改过的语法，您可以将它们转换为 Doxygen 可以读取的特殊注释。此外，通过使用一些关键字，您可以改进格式。此外，Doxygen 还有一些特殊功能，我将在下一节中重点介绍。

功能

大部分工作已经通过您对源代码的常规注释完成。但是通过一些调整，您可以轻松增强 Doxygen 的输出。

Markdown

为了进行高级格式化，Doxygen 支持 Markdown 语法和 HTML 命令。在 opensource.com 的下载部分中，有一个 Markdown 速查表可用。

主页

除了您自定义的标题之外，当您打开 html/index.html 时，您将获得一个几乎空白的页面。您可以使用特定关键字向这个空白空间添加一些有意义的内容。由于主页通常不专用于特定的源代码文件，您可以将一个包含主页内容的普通文本文件添加到项目的根目录中。您可以在 GitHub 上的示例中看到这一点。其中的注释产生以下输出

The Doxygen Example Documentation field now contains headings and documentation: Introduction, Running the example, System requirements, and Building the code, with step by step examples and code snippets (all can be found in the example on GitHub)

图片来源：

(Stephan Avenwedde，CC BY-SA 4.0)

自动链接生成

如上所述，Doxygen 会自动识别您何时引用代码的现有部分，并创建指向相关文档的链接。请注意，只有当您引用的部分也记录在案时，自动链接创建才有效。

更多信息可以在官方文档的自动链接生成下找到。

组

ByteStream 类具有用于写入 (<<) 和读取 (>>) 的重载流运算符。在上面特殊注释部分的类概述中，您可以看到运算符声明被分组为写入和读取。这些组在 ByteStream 头文件中定义和命名。

分组是使用特殊语法完成的：您以 @{ 开始一个组，并以 }@ 结束它。在这些标记内的所有成员都属于这个组。在头文件 ByteStream.h 中，它是这样实现的

/** @name Writing
* Operators for writing to the stream
* @{
*/

(...)

/** @}
* @name Reading
* Operators for reading from the stream
* @{
*/

(...)

/** @} */

您可以在 Doxygen 文档的分组下找到有关分组的更多信息。

LLVM 支持

如果您使用 Clang 构建，您可以将标志 -Wdocumentation 应用于构建过程，以让 Clang 检查您的特殊注释。您可以在 LLVM 用户手册或 Dmitri Gribenko 的演示文稿中找到有关此功能的更多信息，这两者都在 Clang 网站上。

Doxygen 的应用

Doxygen 最初于 1997 年发布，因此已经存在多年了。尽管它历史悠久，但许多项目都使用 Doxygen 来创建他们的文档。一些示例包括 NASA 的 F Prime 飞行软件框架、图像处理库 OpenCV 和软件包管理器 RPM。您还可以在其他领域找到 Doxygen 语法，例如内容管理平台 Drupal 的文档标准。

一个警告：使用 Doxygen 的一个缺点是它输出的 HTML 文档具有 90 年代网页的外观和感觉。使用 Doxygen 也很难描述元编程和模板编程的架构。对于这些情况，您可能会选择 Sphinx 而不是 Doxygen。立即下载 Doxygen 速查表。

标签

文档