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

注释不能完全取代文档，但是有方法可以使用注释来生成文档。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 文件。用空的配置文件生成的文档如下图：