6

我正在编写一个 C++ 静态库，并且我一直在对实现文件中的 doxygen 注释进行评论。我从来没有真正关心过文档，但我现在正在做一些需要为用户做好记录的东西，而且我正在尝试用更好的软件工程来取代我以前只想编码而不是文档的坏习惯实践。

无论如何，前几天我意识到我需要几种不同类型的文档，一种用于库用户（doxygen 手册），然后为我自己或未来的维护者提供更多处理实现细节的评论。

我的解决方案之一是将文件、类和方法的 doxygen 注释放在实现文件的底部。在那里它们会不碍事，我可以在方法定义中/周围包含普通注释以使程序员受益。我知道这需要更多的工作，但这似乎是我实现两种不同类型的评论/文档的最佳方式。您是否同意或有任何可能有用的解决方案/原则。我环顾了该站点，但实际上找不到任何处理此问题的线程。

另外，我真的不想在界面文件中乱扔注释，因为我觉得让界面自己说话会更好。如果用户需要更深入地了解库界面，我宁愿将手册作为用户可以查看的地方。我在正确的轨道上吗？

非常感谢任何想法或评论。

编辑：感谢大家的评论。我从听到他们的声音中学到了很多。我想我对如何将我的用户手册与对维护者有用的代码注释分开有了更好的理解。我喜欢@jalf 关于拥有“散文”风格手册的想法，该手册有助于解释如何使用该库。我真的认为这比参考手册要好。话虽这么说……我也觉得参考手册可能真的派上用场了。我想我会将他的建议与其他人的想法结合起来，并尝试创建一个混合体。（链接到参考手册的散文手册（使用 doxygen 标记，如 page、section、subsection）。）我喜欢@jalf 的另一个建议代码的想法是没有完整的手动交错插入其中。我可以通过将我所有的 doxygen 注释放在实现文件的底部来避免这种情况。这样可以使标头干净，实现干净，以放置对维护实现的人有用的注释。我们将看看这在现实中是否可行。这些只是我对到目前为止所学到的东西的想法。我不肯定我的方法会奏效，甚至是实用的。只有时间证明一切。

4

6 回答 6

6

我认为最好的方法是使用 Doxygen 作为头文件来描述（向用户）如何使用每个类/方法，并使用 .cpp 文件中的注释来描述实现细节。

于 2010-01-19T02:18:58.577 回答
6

我通常认为用户的评论不应该内联在代码中，如 doxygen 评论或类似的东西。它应该是一个单独的文件，散文形式。作为该库的用户，我不需要或不想知道函数的每个参数的含义。希望这很明显。我需要知道函数的作用。我需要知道它为什么这样做以及何时调用它。我需要知道适用的前置条件和后置条件。当我调用这个函数时，它做了什么假设，它返回时提供了什么保证？

图书馆用户不需要评论，他们需要文档。在实际的文本文档中描述库的结构、工作方式和使用方法，并在代码之外进行。

当然，代码可能仍然包含针对维护者的注释，解释为什么实现看起来像它的样子，或者如果它不明显，它是如何工作的。但是库用户需要的文档不应该在代码中。

于 2010-01-19T03:10:56.897 回答
4

做得好，Doxygen 注释在阅读代码和阅读生成的 HTML 时都非常有用。所有的困难都在于干得好。

我的方法如下：

  • 对于库的用户，我将 Doxygen 注释放在头文件中，通过详细说明所有参数、返回值和可能的副作用来解释该函数的用途以及如何使用它。我尝试对其进行格式化，使生成的文档成为参考手册。

  • 对于维护人员，只要自我注释代码不够用，我就会在实现文件中添加基本（不是 Doxygen）注释。

此外，我编写了一个 Doxygen 格式的特殊介绍文件（除了代码），以用户指南的形式向 libray 的新用户解释如何使用库的各种功能，其中指向参考手册的详细信息。这个介绍出现在 Doxygen 生成的文档的首页。

于 2010-01-19T12:45:25.127 回答
3

Doxygen 允许通过\internal命令和INTERNAL_DOCS选项创建两个版本的文档（一个供用户使用，另一个供“内部使用”）。也可以使用条件部分进行更细粒度的控制（参见\if命令和ENABLED_SECTIONS选项。）

正如其他人已经指出的那样，为用户（有时也包括维护人员）提供比严格的代码注释更高级别的东西也很有用。Doxygen 也可以用于此，与\mainpage， \page， [sub[sub]]section 和 \par 命令

于 2010-01-19T14:04:51.650 回答
1

我建议你看看这篇论文：http ://www.literateprogramming.com/knuthweb.pdf

我通常将这些想法应用到我的项目中（使用 Doxygen）。它还有助于使文档保持最新，因为不必离开 IDE，因此可以在编码时进行注释，然后修改最终的 pdf 文档以查看需要更新或更详细的内容。

根据我的经验，Doxygen 需要一些工作才能使 pdf 看起来不错，图形和图片到位等，但是一旦你找到了方法并了解了该工具的局限性，它就可以很好地完成工作。

除了 Kyle Lutz 和 Eric Malefant 已经说过的话，我的建议是将有关相关类的长解释放在它自己的文件中（我为此使用了一个头文件），并使用 Doxygen 标签添加对其他部分的引用。你只需要在 Doxygen 配置文件中包含这些头文件（使用模式匹配）。这样可以避免标题过于混乱。

于 2010-01-19T21:08:29.897 回答
1

没有快速简单的答案，好的文档很难。

我个人觉得分层模型是最好的。

  • 散文中的高级文档。图片和视频都非常合适。
  • 参考级别的文档应该是 Doxygen（干得好 doxygen，而不仅仅是临时评论）。
  • 维护者文档不应出现在参考文档中，但正如 Éric 所指出的那样，它们仍然可能是 doxygen。

我真的很喜欢RakNet中使用的文档风格。作者使用了大量的 Doxygen 注释并提供了生成的参考手册。他还提供了一些简单的 html 教程。最重要的是，他提供了一些更复杂功能的视频演练。

另一个很好的例子是SFML。质量不如 RakNet，但仍然非常好。他在doxygen 生成的文档中提供了一个很好的概览页面。有一些纯 html 教程和纯 html 功能/概述页面。

我更喜欢这些风格，因为当我刚开始时，Doxygen 生成的文档通常水平太低，但一旦我进入了最佳状态，它就会非常简洁。

于 2010-02-10T17:08:20.697 回答