65.9K
CodeProject 正在变化。 阅读更多。
Home

10 分钟文档化您的代码

peterchen
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.91/5 (150投票s)

2003 年 1 月 20 日

CPOL

13分钟阅读

viewsIcon

1226218

downloadIcon

6894

在几个简单的步骤中设置 doxygen，一个免费的代码文档工具。

注意：一些单独的文件下载托管在外部网站。我为了方便和更方便地访问本文档，将它们提供给了大家。其他链接指向 doxygen 主页上的在线手册。（我猜这已经给我惹了法律麻烦。）

欢迎！

Doxygen 是一个免费1)工具，它可以提取特定的源代码注释并分析您的代码声明，从而生成全面的在线文档，类似于 Visual Studio.NET 中的Tools/Build Comment web pages命令。如果您也想为 VC++6 拥有类似的功能，或者需要更多的灵活性和选项，那么本文就是为您准备的。

设置完成后，Doxygen 只需点击一下即可生成代码的 HTML 文档。文档编写仍然是您的工作，如果您想要高质量的文档，那仍然是您的责任。但是，一个自动化系统可以完成许多常规任务，而设置“一键式”文档过程是第一步：如果您能立即看到您的努力成果，那么添加正确的注释类型就会很快变得自然。

1) Doxygen 由 Dimitri van Heesch 编写，并根据GNU 公共许可证 (GPL)发布。doxygen 创建的文档不受 GPL 的影响。更多信息请参阅Doxygen 主页。

今天我有什么要给你们的？

  1. 设置方法 - 一个快速的循序渐进指南，介绍如何设置 doxygen 并将其集成到 VC++ 6 中
  2. 基础文档编写 - 如何让 doxygen 理解您的注释。
  3. 理由 - 为什么要使用 doxygen？（如果您已经信服，可以跳过）
  4. 使用 Doxygen - 讨论示例设置（来自 1），并介绍 doxygen 最重要的功能。
  5. 附加资源（目前不多）

那么，让我们开始吧！

设置

本文将向您展示如何将 doxygen 集成到 VC++ 6 中，并为其一个项目进行设置。我假设您已经有一个要尝试 doxygen 的项目（如果没有，任何 C++ 文件都可以）。整个过程大约需要 5 分钟（取决于您的下载速度）。

注意：当工作区包含子文件夹中的多个项目时，此设置效果不佳。请参阅下文。

doxygen 二进制文件 [^] 1. 下载 Win32 二进制文件并安装。在接下来的说明中，我将假定您已将 doxygen 安装在 c:\program files\doxygen。
doxygen 工具 2. 下载并解压我的 doxygen 工具，并将它们保存在您选择的文件夹中。它们包含了本文提到的所有单独文件。
添加 VC++ 工具
"doxygen"		 添加一个新的自定义工具，名为“DoxyGen”，并设置以下参数：
  • 命令：c:\program files\doxygen\bin\doxygen.exe （或您安装的位置）
  • 参数：“$(WkspDir)\default.doxygen" （配置文件 - 包含引号！）
  • 初始目录：“$(WkspDir)"
  • 选中“使用输出目录”框。
添加 VC++ 工具
"查看结果"		 添加另一个工具，用于查看结果。新建一个“View DoxyDoc”工具，用于查看结果。
  • 命令：您喜欢的浏览器，例如 c:\program files\internet explorer\iexplore.exe
  • 参数：“$(WkspDir)\doxydoc\index.html"
  • 初始目录：留空。
添加到项目
  • 打开您想添加文件的项目。
  • 将 default.doxygen 文件复制到您的项目文件夹中（此文件包含 doxygen 的配置选项）。
  • 在 VC++ 中打开它进行编辑。
  • 将 ***PROJECT NAME*** 更改为您的项目名称。
  • 右键单击文件，然后选择“Insert File into Project / <project name>”。如果您使用 VSS，也请将其添加到 SourceSafe。
您完成了！试试吧！ 从菜单中选择 Tools/doxygen，然后观看奇迹发生（doxygen 会在输出窗口中记录其进度和错误）。
选择 Tools/View results 探索文档。

“Main Page”可能相当无聊。点击顶部的“Data Structures”浏览您的类等。

基础文档编写

除非您已经使用 doxygen 能理解的某种注释风格，否则文档几乎是毫无意义的。那么您可以做什么？

1. 在类和结构体前添加一个注释块，使用 ///

只需为注释块使用 ///。

/// SNAPINFO holds the data for calculating a modified window rect. Since it
/// only works on coordinate rects, it can be used without any actual Windows.
struct SNAPINFO
{
   // ...
}

2. 为类成员声明添加简短注释。

如果您在成员前面放置单行注释，请使用 ///。如果您将注释放在成员后面，请使用 ///<。

struct SNAPINFO
{
    /// Init, using a pre-change and a post-change rectangle
    void Init(RECT const & oldRect, RECT const & newRect, DWORD snapwidth); 

    void SnapHLine(int y); ///< Snap to a horizontal line
}

3. 为方法实现添加详细描述。

与类一样，使用 /// - 注释块。

/// Initializes the structure with an old an a new rectangle.
/// use this method if the window is about to be moved or resized (e.g. in
/// WM_SIZING or WM_MOVING handler)
void Init(RECT const & oldRect, RECT const & newRect, DWORD snapwidth)
{
  // ...
}

我为另一个文章中的一个小类准备了一个示例，这个类几乎没有任何可文档化的注释。

原始代码 [^] 文档 [^]
添加了简短注释 [^] 文档 [^] 13 行新增
2 行注释风格已修改
添加了方法描述 [^] 文档 [^] 14 行额外添加（大量复制粘贴）
不带 EXTRACT_ALL 选项 文档 [^]

注意：一旦您为重要类添加了基本的 doxygen 注释，就应该关闭 EXTRACT_ALL 选项（如 default2.doxygen 中所示）。未注释的类将被排除，这将大大减少详细文档部分的混乱。

原理

在使用 VS.NET 时，我注意到“Tools/Build comment web pages”极大地激励我为我的源代码添加有用的函数和类注释。由于我有一个庞大的 VC6 代码库需要维护，其中大部分已经有注释，但没有提取工具，我便转向了 doxygen，并在相对较短的时间内将其运行起来。所以，也许您还没有信服，那么这里有三个问题给您，附带一些（暗示性的）答案。

第一个问题：您需要软件文档吗？

原因很多：

  • 您的公司要求一些文档。
  • 您不确定半年后是否还记得自己写的所有代码。
  • 您的同事总是问关于您工具库的“我该如何做这个”之类的问题。
  • 您计划退休或离开，不想让您宝贵的代码最终被随意修改或重写，仅仅因为别人没有花时间去理解它。
  • 您感觉更好。

当然，您可以相当长的时间内没有文档，特别是当您独自工作或在一个非常小的团队中时。但是，一旦项目变得相当大，您就会开始*想要*一些正式的文档。并且越早开始越好。准备好一个可用的工具，就能扫除最大的障碍——开始。

第二个问题：为什么使用自动化系统？

  • 文档保持最新。
    您更有可能修改您正在处理的函数顶部的注释，而不是启动 MS Word，查找函数文档，然后进行修改。
  • 重用您自己的注释。
    假设您已经发现了为自己的代码添加注释的优点，那么您的注释的市场价值就翻倍了。
  • 自动格式化和交叉链接。
    通过一些简单的标记，您可以获得专业且一致的文档，并创建指向所有重要实体描述的链接。忘记与 MS Word 斗争吧。
  • 代码内注释携带重要的元信息。
    并非所有重要信息都能从实际的“原始”源代码中获得。接口契约、前置条件和后置条件、副作用、特殊参数的含义等，都需要任何维护代码的人了解——无论是您自己还是其他人。这些注释的正式风格，结合解析器（如 doxygen 的 XML 导出），可以使这些信息以定制的格式提供给各种接收者：项目管理、测试人员等等。

第三个问题：为什么选择 doxygen？

  • 它是免费的——所以它非常适合：
    • 吝啬鬼。
    • 偷偷将其引入开发过程，以防在您那里没人关心。
    • 评估自动化文档系统是否以及如何能帮助您。
    • 了解您在寻找更好的东西时需要哪些功能。
  • 开源且带安装程序。
    它相当方便使用（也请参阅下面的“使用 Doxygen”），所以有源代码是一个额外的优势。
  • 可配置。
    通过一个基本的样式表，以及对 doxygen 配置文件中的选项进行调整（使用 doxywizard 很容易），您可以自定义文档的许多方面以满足您的需求。

文档化现有代码库。

也许您有一个大型项目，您希望有人有耐心添加可提取的注释。然而，想到要审查 10,000 行代码并对其进行文档化，您就会不寒而栗。这里有一些建议：

  • 为项目设置 doxygen。这只需要五分钟，否则什么也不会发生。
  • 记录您新写的所有代码。
  • 修补您正在处理的代码。如果您无论如何都要修改某个函数，那么添加一些额外的注释是最简单的。通常只是复制/调整一些现有注释使其看起来更漂亮。
  • 午餐休息前花 5 分钟添加注释。或者：每次访问 CodeProject 休息室时，为一处函数添加注释。

很快您就会在文档化代码方面感到更“流畅”，为现有类添加简短注释只需几分钟。如果文档的好处开始显现，您就会更有动力继续下去。

使用 Doxygen

上面使用的设置相当通用。您可以使用 doxygen -g 或使用 doxywizard 生成一个默认配置文件。后者可以轻松地玩转各种选项。

对于每个可文档化的实体，doxygen 会查找一个简短注释和一个详细描述。简短注释会添加到各种概述（如类成员列表）中。

注释风格

Doxygen 也识别其他注释格式——我之所以选择以上格式，是出于个人喜好以及与 .NET 中常用的格式的兼容性。有关完整列表，请参阅 doxygen 文档中的代码注释。

其他 doxygen 选项

在 default.doxygen 中，我更改了一些默认选项，特别是：

  • EXTRACT_ALL 启用：因此，即使是“未注释”的代码也会生成一些内容。
    我强烈建议现有项目首先为最重要的类声明和方法添加一些文档，然后关闭 EXTRACT_ALL 选项。这可以减少文档的混乱，并更有动力去注释那些尚未被注释的内容。
  • JAVADOC_AUTOBRIEF：这允许在一个块中同时拥有简短注释和详细描述（尽管名称如此，它也适用于 C++ 源文件）。
    注释块的第一行（直到第一个句号）用作简短描述。
  • WARN_FORMAT 设置为 $file($line): $text——这样您就可以双击输出窗口中的 doxygen 警告消息跳转到相应的源代码行。
  • INPUT：我添加了一个单独的“.”作为 INPUT 目录，并选中了 RECURSIVE 选项。这将扫描工作目录（在 VC++ 自定义工具中设置为工作区文件夹），并添加了一份合理的要扫描的文件列表（.IDL 文件效果也很好！）。您也可以指定排除模式（例如，对于 ATL 项目，使用 *_i.c 和 *_p.c 来排除一些内部结构）。
  • 源代码浏览器：我启用了 SOURCE_BROWSER 选项，以便包含源代码并进行交叉链接（doxygen 会删除所有 doxygen 风格的注释，但保留所有其他注释）。
  • 我禁用了 REFERENCED_BY_RELATION 和 REFERENCES_RELATION 选项。当您想探索复杂代码的相互依赖关系时，它们可能很有价值，但对我正在处理的事情来说，它们只是增加了混乱。
  • 对于 HTML_OUTPUT，我将其设置为 doxydoc 目录（它将在工作目录下方创建）。
    提示：在 doxygen 配置文件中指定目录名时 -
    • 如果它包含空格，请将其放入引号中（对于其他选项来说，这也是一个好主意）。
    • 不要以反斜杠结尾——doxygen 使用它来将参数列表分布到多行。
    • doxygen 会尝试创建不存在的输出目录，但无法生成多级目录。
  • GENERATE_TREEVIEW：虽然我在默认设置中将其禁用，但您应该尝试一下！

文档标记

Doxygen 允许在注释中使用简单的标记（我在示例文档中也使用了一些），它们以反斜杠或 @ 开头。这里列出了最重要的几个：

\param name descripiton 用于记录函数参数。请参阅完整的示例源代码和文档，了解其外观。
\return description 描述函数返回什么。
\b \c \e 将下一个词分别设置为粗体、斜体或等宽字体。例如：
/// 您可以将文本设置为 \b 粗体、\e 斜体，或设置为 \c 等宽字体。
结果是
您可以将文本设置为粗体、斜体，或设置为等宽字体。
\code
\endcode		 分别开始和结束代码段。（它将被格式化得很好）。
\n 强制换行。
\internal 开始一个“内部信息”（如实现细节）段落。该段落仅在 INTERNAL_DOCS 选项启用时包含。
\mainpage 指示以下部分应出现在主页上。这是介绍您最重要的类等的绝佳位置。（实体将被交叉链接）。
\par
\par Title		 开始一个新段落（可选地带有一个段落标题），也可以在其他段落（如 \param）内部使用。
列表 Doxygen 会自动创建一个列表，如果多行从同一位置开始用破折号。可以通过以连字符和哈希符号（-#）开头来创建编号列表。有关更多信息，请参阅 doxygen 文档。
更多...
（doxygen 文档）		 Doxygen 支持许多其他标签，其中许多允许进一步标记，或旨在与 XML 导出结合使用。（例如，您可以标记前置条件和后置条件、错误、测试用例、待办事项等的规范）。
HTML
（doxygen 文档）		 Doxygen 也支持 HTML 标签，这些标签会或多或少正确地转换为其他输出。

额外资源

宏

为了方便编写文档，可以设置一些绑定到热键的自动文本。我只使用了一些宏，并手动为它们分配了快捷方式：设置有点麻烦，但值得。

  • 将 doxygen.dsm 复制到 [DevStudo]\Common\MSDev98\Macros 文件夹。
  • 启动 VC++，选择 Tools/Customize...
  • 在“Add ins and macros”选项卡上，启用 doxygen.dsm 宏文件。
  • 在 Keyboard 选项卡上，选择 Category 下的“Macros”，然后为您喜欢的命令分配快捷方式。

这是我使用的宏列表：

宏名称 描述 我的快捷方式
DoxyComment 三个斜杠和一个空格（我很少使用它，但它在那里）。 Ctrl-# （德语键盘..）
DoxyCommentNL 换行 + '/// '——非常适合编写块注释（只需按 Ctrl-Enter 而不是 Enter）。 Ctrl-Enter
DoxyCommentPrev '///< '：用于声明后面的简短注释。 Ctrl-Shift-#
DoxyDocFunction 用于注释函数的简单头部。 Ctrl-Shift-F

样式表

您可以通过调用以下命令生成默认的 doxygen 样式表、HTML 标题和页脚：

doxygen -w html <header_name> <footer_name> <stylesheet_name>

我已经为您做好了：doxygen_header.html、doxygen_footer.html 和 doxygen_default.css。

默认样式表是您自己的良好起点。

DoxyWizard

最后，一个小建议：Doxygen 配套提供了 DoxyWizard，这是一个用于编辑配置文件 .doxygen 的 UI 工具。它还可以，它自带的“快速帮助”简要解释了每个选项。由于我所有配置文件都命名为 .doxygen，所以我将此扩展名与 doxywizard 关联起来，这样生活就轻松多了，并且玩转这些选项也更有趣。

其他系统

如果您有其他文档系统的经验，请随时在评论区（不）推荐它们——只要您不进行广告宣传，并保持在 CP 的良好品味范围内。

祝您使用愉快！并且文档编写得当。

© . All rights reserved.