C/C++头文件文档化

Question

在创建C++公共头文件时，您认为最佳实践是什么？

1. 头文件应包含无、简要或详细的文档说明？我见过各种不同的写法，从几乎没有文档（依赖于一些外部文档）到详细描述不变量、有效参数、返回值等等。我不确定自己更喜欢哪种方式。大量的文档很好，因为您总是可以从编辑器中访问它，但另一方面，非常简短的文档可以在一两页文本中显示完整的接口，更好地概述了类的功能。

2. 假设我采用简要或详细的文档说明方式，我希望像javadoc一样记录返回值、参数等。在C++中，最佳的约定是什么？据我所知，Doxygen可以处理JavaDoc风格的文档，但在选择采用javadoc风格文档之前，我应该了解是否还有其他约定和工具。

- Laserallan

Answer 1

通常，我会将接口的文档（参数、返回值、函数执行内容）放在接口文件 (.h) 中，将实现的文档（函数如何执行）放在实现文件 (.c, .cpp, .m) 中。

在类的声明之前，我会撰写一个概述，以便读者立即获得基本信息。

我使用的工具是 Doxygen。

- mouviciel

Answer 2

1. 我认为在头文件中加入一些文档说明会大大提高调试效率，因为信息与代码相邻而不是分散在其他文档中。一般来说，我会将API（返回值、参数、状态变化等）的文档说明放在代码旁边，而将高层次的架构概述放在单独的文档中（以便更全面地了解整个系统是如何组合在一起的；由于这通常涉及到多个类，所以很难与代码放在一起）。

2. 根据我的经验，Doxygen是可以的。

- João da Silva

Answer 3

我认为Doxygen是生成文档最常用的平台，据我所知，它可以涵盖JavaDoc注释（当然不仅限于此）。我已经使用过Doxygen来为C语言生成文档，效果还不错，但我认为它更适合用于C++。你也可以考虑一下robodoc，但我觉得奥卡姆剃刀原理会告诉你最好选择Doxygen。

关于文档量的问题，我从来不喜欢文档，但无论我是否喜欢，有更多的文档总比没有文档要好。我会将API文档放在头文件中，实现文档放在实现文件中（这很合理，不是吗？:))。这样，IDE就有机会在自动完成时将其捕获并显示出来（例如，Eclipse针对JavaDocs做到了这一点，Doxygen是否也能这样呢？），这一点绝不能低估。JavaDoc还有一个额外的怪癖，它使用第一句话（即第一个句号之前的内容）作为简要说明，不知道Doxygen是否也这样做，但如果是，写文档时应该考虑到这一点。

大量文档可能过时的风险，但将文档保持接近代码将使人们有机会将其更新，因此您应该将其保存在源代码/头文件中。但是不应该忘记的是文档的产生。是的，有些人会直接使用文档（通过IDE或其他方式，或只是阅读头文件），但有些人更喜欢其他方式，因此您可能要考虑将您的（定期更新的）API文档在线发布，并制作漂亮且可浏览的页面，以及如果您针对*nix开发人员，则还要生成man文件。

这是我的个人见解。

- roe

Answer 4

将足够的信息写入代码，以便它可以独立存在。在我参与的几乎每个项目中，文档都是单独的，而且很容易过时或者没有完成。部分原因是如果文档成为一个单独的任务，管理层通常不会把它纳入预算中。根据我的经验，将文档编写在代码中更好地融合在一起。

以大多数编辑器认识的块形式编写文档；对于C++，这似乎应该是/*而不是//。这样你就可以折叠它并只看到声明。

- Pete Kirkham

Answer 5

也许你会对gtk-doc感兴趣。它的设置和使用可能有点棘手，但你可以从源代码中获得漂亮的API文档，看起来像这样：

字符串实用函数

- kliketa