在 Linux 上用 Doxygen 生成源代码文档
| 2023-09-26 10:33 评论: 1
Doxygen 是一款广泛使用的开源文档生成工具,它通过代码注释来生成文档。
在试着熟悉别人的代码时,你总希望他们留下的代码注释能对你理解代码有所帮助。同理,无论为了自己还是其他人,编写代码时写注释是好习惯。所有编程语言都有专门的注释语法,注释可以是一个单词、一行文字、甚至是一整段话。编译器或解释器处理源代码时会忽略注释。
注释不能完全取代文档,但是有方法可以使用注释来生成文档。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
表示 生成。现在应该会出现一个名为 Doxyfile
的新文件。通过命令调用 Doxygen:
doxygen
现在应该能会有两个新文件夹:
html/
latex/
默认情况下,Doxygen 会同时输出 LaTeX 和 HTML 格式的文档。本文主要关注 HTML 文档。你可以在 Doxygen 官方文档的入门小节中找到关于 LaTeX 格式输出的更多信息。
双击 html/index.html
打开 HTML 文件。用空的配置文件生成的文档如下图:
现在我们试着修改 Doxyfile
文件,并在源代码中添加特殊注释。
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 来检验修改是否生效了。可以在调用 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 基于此生成参数列表:
值得注意的是 Doxygen 为 buffer()
和 size()
方法自动生成了链接。相反,Doxygen 忽略了析构函数前的注释,因为它并没有使用特殊注释:
// Destructor
~ByteStream();
现在你已经看到 Doxygen 的绝大部分功能了。通过使用一种稍微改良的注释格式,让 Doxygen 能够识别它们。通过使用一些关键字,你甚至可以进一步控制格式化。在下一节中,我会进一步介绍 Doxygen 的其它特性。
其它特性
现在几乎所有的工作都可以通过对源代码注释的方式完成。通过一些微调,你可以轻松地优化 Doxygen 的输出。
Markdown 格式
为了进阶的格式化,Doxygen 支持 Markdown 和 HTML 命令。Markdown 速查表可以在 这里 下载到。
项目主页
除了自定义页眉之外,html/index.html
几乎没有其它内容了。你可以通过使用关键字向其中添加一些有意义的内容。因为主页通常不是针对某个源代码文件的,你可以将要显示在主页的内容放到项目根目录下的一个单独文件中。示例项目中就是这样做的,其输出效果如下:
自动链接生成
上面已将提到了,当你引用代码的其它部分时,Doxygen 会自动识别并生成相应链接。但要注意,这要求被引用部分也有文档才行。
更多信息可以在官方文档的自动链接生成中找到。
分组
ByteStream
类重载 了的读写流操作符 (<<
和 >>
)。在类的概览中可以发现操作符被分为读和写两组。分组是在 ByteStream
的头文件中定义的。
分组的语法以标记 @{
开始,以 }@
结束。在标记范围中的内容都属于这个分组。在 ByteStream.h
中的实现如下:
/** @name Writing
* Operators for writing to the stream
* @{
*/
(...)
/** @}
* @name Reading
* Operators for reading from the stream
* @{
*/
(...)
/** @} */
你可以在官方文档的分组中找到更多相关信息。
LLVM 支持
如果你用 Clang 构建项目的话,可以通过使用 -Wdocumentation
选项让 Clang 对特殊注释进行检查。想了解该特性的更多信息,可以参考 LLVM 用户手册和 Dmitri Gribenko 的展示报告,它们可以在 Clang 网站上找到。
谁在用 Doxygen
Doxygen 是在 1997 年首次发布的。尽管有些年头了,现在仍然有很多项目在使用 Doxygen。比如 NASA 的飞行软件框架 F Prime、图像处理库 OpenCV、包管理器 RPM。你还可以在其它领域发现 Doxygen 语法标记的身影,比如内容管理平台 Drupal 的文档标准中。
注意:Doxygen 输出的 HTML 文档风格类似于九十年代网页。并且它也难以描绘元编程和模板编程架构。在这些情况下,你应该选择 Sphinx 而不是 Doxygen。
(题图:MJ/4d354094-397e-4ac5-a80d-25b9c736ede5)
via: https://opensource.com/article/22/5/document-source-code-doxygen-linux
作者:Stephan Avenwedde 选题:lkxed 译者:toknow-gh 校对:wxy