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

注释不能代替文档,但有一种方法可以使用您的注释轻松生成文档。认识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生成一个标准模板。为此,请导航到项目的根目录并运行:

祖兹100097

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

doxygen

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

• html/

• latex/

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

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

图片来源:

(Stephan Avenwedde,CC BY-SA 4.0)

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

更多 Linux 资源

Linux 命令备忘单

高级 Linux 命令备忘单

免费在线课程:RHEL 技术概述

Linux 网络备忘单

SELinux 备忘单

Linux 常用命令备忘单

什么是Linux容器?

我们最新的 Linux 文章

Doxyfile

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

第35行:项目名称

您可以在此处指定项目名称,该名称将在标题行和浏览器选项卡中可见。

# PROJECT_NAME 标记是单个单词(或由

# 双引号,除非您使用的是 Doxywizard),它应该标识

# 为其生成文档的项目。此名称用于

# 大多数生成页面的标题和其他一些地方。

# 默认值为:我的项目。

PROJECT_NAME u003d “我的项目”

第47行:项目简介

简要说明也将显示在标题中,但字体较小。

# 使用 PROJECT_BRIEF 标签可以提供可选的一行描述

# 用于显示在每页顶部的项目,并应为查看者提供

# 快速了解项目的目的。保持描述简短。

PROJECT_BRIEF u003d "在 C++ 中使用 Doxygen 的示例"

第 926 行:包含子目录

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

# RECURSIVE 标记可用于指定子目录是否应该

# 也可以搜索输入文件。

# 默认值为:否。

递归 u003d 是

第 1769 行:禁用 LaTeX 输出

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

# 如果 GENERATE_LATEX 标签设置为 YES,doxygen 将生成 LaTeX 输出。

# 默认值为:YES。

生成_LATEX u003d 否

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

图片来源:

(Stephan Avenwedde,CC BY-SA 4.0)

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

特别评论

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

我将以构造函数和析构函数为例:

/*! @brief 构造函数,它需要一个外部缓冲区来操作

*

* 指定的缓冲区已经存在。

* 内存和大小可以通过 buffer() 和 size() 访问。

*

* @param[in] pBuf 指向现有缓冲区的指针

* @param[in] size 现有缓冲区的大小

*/

ByteStream(char* pBuf, size_t size) noexcept;

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

Doxygen 中的注释分为两个部分,一个_brief_ 描述和一个_detailed_ 描述。这两个部分都是可选的。在上面的代码示例中,注释块指的是下面的代码行,即构造函数的声明。@brief后面的语句将在紧凑类概述中显示:

图片来源:

(Stephan Avenwedde,CC BY-SA 4.0)

在空行之后(空行被视为段落分隔符),构造函数的实际文档开始。使用@param[in/out]关键字,您可以标记传递给构造函数的参数,Doxygen 会从中制作出清晰的参数列表:

图片来源:

(Stephan Avenwedde,CC BY-SA 4.0)

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

// 析构函数

〜字节流();

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

特点

大部分工作已经通过您对源代码的定期评论完成。但是通过一些调整,您可以轻松增强 Doxygen 的输出。

降价

对于高级格式化,Doxygen 支持 Markdown 语法和 HTML 命令。在 opensource.com 的下载部分中有一个 Markdown 备忘单。

主页

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

图片来源:

(Stephan Avenwedde,CC BY-SA 4.0)

自动链接生成

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

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

群组

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

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

/** @name 写作

* 用于写入流的运算符

* @{

*/

(...)

/** @}

* @name 阅读

* 用于从流中读取的运算符

* @{

*/

(...)

/** @} */

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

LLVM 支持

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

使用 Doxygen 的地方

Doxygen 于 1997 年首次发布,因此它已经存在了好几年。尽管年代久远,许多项目还是使用 Doxygen 来创建他们的文档。一些例子是 NASA 的F Prime飞行软件框架、图像处理库OpenCV和包管理器RPM。您还可以在其他领域找到 Doxygen 语法,例如在内容管理平台Drupal的文档标准中。

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