如何在Linux上用Doxygen生成源代码文档

如何在Linux上用Doxygen生成源代码文档

今天小编介绍如何在Linux上用Doxygen生成源代码文档的介绍，接下来IT袋网小编就来介绍。

在试着熟悉别人的代码时，你总希望他们留下的代码注释能对你理解代码有所帮助。同理，无论为了自己还是其他人，编写代码时写注释是好习惯。所有编程语言都有专门的注释语法，注释可以是一个单词、一行文字、甚至是一整段话。编译器或解释器处理源代码时会忽略注释。

注释不能完全取代文档，但是有方法可以使用注释来生成文档。Doxygen是一个开源的文档生成工具，它能够根据代码注释生成 HTML 或 LaTeX 格式的文档。Doxygen 让你在不用额外操作的情况下创建代码结构概览。尽管 Doxygen 主要是用来给 C++ 生成文档的，它对其它语言同样适用，比如 C、Objective-C、 C#、 PHP、Java 和 Python 等。

要使用 Doxygen，你只需要在源代码中使用 Doxygen 能够识别的语法来写注释。Doxygen 会扫描源码文件，然后根据这些特殊注释生成 HTML 或 LaTeX 文档。下面的示例项目会演示如何使用 Doxygen 注释，以及文档是如通过注释生成出来的。示例代码可从 GitHub上获得，本文中也将引用Doxygen 手册及文档的相关章节。

在 Linux 上安装 Doxygen

在 Fedora 上可以通过软件包的形式安装 Doxygen。打开终端运行命令：

sudo dnf install doxygen

在基于 Debian 的操作系统上，可以通过以下命令来安装：

sudo apt-get install doxygen

使用

安装完 Doxygen 后，你需要在项目中按 Doxygen 可以识别的格式来注释代码，还要提供一个 Doxyfile 配置文件来控制 Doxygen 的一些行为。

注意：如果你用的是 GitHub 上的示例项目，你可以忽略下面一步。

如果 Doxyfile 文件不存在，你可以用 Doxygen 生成一个标准 Doxyfile 模板文件。切换到项目根目录下，运行：

doxygen -g

参数-g表示 生成generate。现在应该会出现一个名为Doxyfile的新文件。通过命令调用 Doxygen：

doxygen

现在应该能会有两个新文件夹：

• html/
• latex/

默认情况下，Doxygen 会同时输出 LaTeX 和 HTML 格式的文档。本文主要关注 HTML 文档。你可以在 Doxygen 官方文档的入门小节中找到关于 LaTeX 格式输出的更多信息。

双击html/index.html打开 HTML 文件。用空的配置文件生成的文档如下图：

现在我们试着修改Doxyfile文件，并在源代码中添加特殊注释。

Doxyfile 文件

在Doxyfile文件中可以定义大量的可调选项，本文通过介绍示例项目的Doxyfile文件我只能覆盖其中很小的子集。

第 35 行：项目名称

你可以在这里指定项目名称，它最终会显示在页眉header和浏览器标签上。

# 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 来检验修改是否生效了。可以在调用 Doxygen 时使用-x选项来查看Doxyfile文件的变更项：

通过调用diff命令，Doxygen 仅显示当前 Doxyfile 文件和模板文件的差异。

特殊注释

Doxygen 通过扫描源代码文件中的特殊注释和关键字来生成 HTML 文档。示例项目中的 ByteStream 类的头文件可以很好地解释特殊注释的用法。

下面用构造函数和析构函数作为示例：

/*! @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之后的文本会显示在类概览小节中：

在空行（空行是段落分隔符）之后是构造函数的实际文档。用 @param[in/out]关键字标注传递给构造函数的参数，Doxygen 基于此生成参数列表：