双重用途代码评论（用户和维护者）...如何？

Question

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

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

我的一个解决方案是将文件，类和方法的doxygen注释放在实现文件的底部。在那里，它们将被排除在外，我可以在方法定义中/周围包含正常注释，以使程序员受益。我知道这是更多的工作，但它似乎是我实现两种不同类型的评论/文档的最佳方式。您是否同意或有任何可能有用的解决方案/原则。我环顾了网站，但无法找到任何处理此问题的主题。

另外，我真的不想在评论中乱丢接口文件，因为我觉得最好让界面说明一切。如果用户需要更深入地了解库接口，我宁愿手册成为用户可以查看的地方。我在这里走在正确的轨道上吗？

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

编辑： 感谢大家的意见。我从听到他们那里学到了很多东西。我想我更好地理解如何将用户手册与对维护者有用的代码注释分开。我喜欢@jalf有关于“散文”风格手册的想法，该手册有助于解释如何使用该库。我真的认为这比参考手册更好。话虽如此......我也觉得参考手册可能真的派上用场了。我想我会将他的建议与其他人的想法结合起来并尝试创建一个混合体。（散文手册（使用doxygen标签，如页面，部分，小节）链接到参考手册。）我喜欢@jalf的另一个建议是没有整个手册插入其中的代码的想法。我可以通过将所有doxygen注释放在实现文件的底部来避免这种情况。这使得头文件清晰，实现干净，以便对维护实现的人发表有用的注释。我们将看看这是否真的有效。这些只是我对迄今学到的知识的看法。我不是肯定的，我的方法可以很好地运作，甚至可以实用。只有时间会证明。

Answer 1

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

Answer 2

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

图书馆用户不需要评论，他们需要文档。描述库的结构，工作原理以及如何使用它，并在实际的文本文档中在代码之外。

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

Answer 3

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

我的方法如下：

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

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

此外，我用Doxygen格式编写了一个特殊的介绍文件（除了代码之外），用于向libray的新用户解释如何使用库的各种功能，以用户指南的形式指出参考细节手册。此介绍显示为Doxygen生成文档的首页。

Answer 4

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

正如其他人已经指出的那样，为严格的代码注释提供更高级别的用户（有时也包括维护者）也是有用的。使用\mainpage，\ page，[sub [sub]]部分和\ par命令

也可以使用Doxygen

Answer 5

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

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

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

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

Answer 6

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

我个人认为分层模型最好。

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

我非常喜欢RakNet中使用的文档样式。作者使用广泛的Doxygen评论并提供生成的reference manual。他还提供了一些plain html tutorials。最重要的是，他提供了video walk-throughs一些更复杂的功能。

另一个很好的例子是SFML。质量不如RakNet好，但它仍然非常好。他在doxygen generated documentation中提供了一个很好的概述页面。有一些plain html tutorials和一个简单的HTML功能/概述页面。

我更喜欢这些样式，因为当我刚刚开始时，Doxygen生成的文档通常太低，但是一旦我处于凹槽状态，就会非常简洁。