C / C ++头文件文档
在C ++中创建公共头文件时，您认为最佳做法是什么？
-
头文件是否应该包含没有，简短或大量的文档？ 我已经看到了从几乎没有文档（依赖于一些外部文档）到大规格的不变量，有效参数，返回值等所有内容。我不确定我更喜欢什么，大文档很好，因为你总是访问它来自您的编辑器，另一方面，带有非常简短文档的头文件通常可以在一页或两页文本上显示完整的界面，从而可以更好地概述可以对类进行的操作。
-
假设我选择简短或大量的文档。 我想要类似于javadoc的东西，其中我记录了返回值，参数等。在c ++中，最好的约定是什么？ 据我所知，doxygen在java doc风格的文档中做得很好，但在使用javadoc样式文档之前，我是否应该注意其他任何约定和工具？
通常我在接口文件（.h）中放置接口的文档（参数，返回值，函数的作用），以及实现文件中的实现文档（函数如何 ）（.c，.cpp， .M）。
我在声明之前写了课程的概述，因此读者可以立即获得基本信息。
我使用的工具是Doxygen。
-
我会在头文件本身中定义一些文档。 它极大地改进了调试，使信息在代码旁边，而不是在单独的文档中。 根据经验，我会在代码旁边记录API（返回值，参数，状态更改等），并在单独的文档中记录高级架构概述（以更广泛地了解所有内容是如何组合在一起的;它是很难将它与代码放在一起，因为它通常一次引用几个类）。
-
根据我的经验，Doxygen很好。
我相信Doxygen是生成文档的最常用平台，据我所知，它或多或少能够涵盖JavaDoc符号（当然不限于此）。 我已经将doxygen用于C，但是OK结果，我认为它更适合C ++。 你可能也想看看robodoc，虽然我认为Occam的Razor会告诉你宁愿选择Doxygen。
关于多少文档，我自己从未成为文档粉丝，但无论我喜欢与否，拥有更多文档总是胜过没有文档。 我将API文档放在头文件中，并在实现中实现文档（按理说，不是吗？）。 :)那样，IDE有机会在自动完成期间选择并显示它（例如，Eclipse为JavaDocs执行此操作，也许也适用于doxygen？），这不应该被低估。 JavaDoc有这个额外的怪癖，它使用第一句话（即直到第一个句号）作为简要描述，不知道Doxygen是否这样做，但如果是这样，在编写文档时应该考虑它。
拥有大量文档存在过时的风险，但是，保持文档接近代码将使人们有机会使其保持最新，因此您应该将其保留在源/头文件中。 不应该忘记的是文档的制作。 是的，有些人会直接使用这些文档（通过IDE或其他任何东西，或只是阅读头文件），但有些人更喜欢其他方式，所以你应该考虑将你的（定期更新的）API文档放在网上，一切都很好，可浏览，如果您的目标是基于* nix的开发人员，也可能生成man-files。
那是我的两分钱。
在代码中加入足够多的东西。 几乎每个项目我都在文档是分开的，它已经过时或没有完成，部分是如果它是一个单独的文档，它就变成了一个单独的任务，部分是因为管理层不允许它作为一项任务在预算中。 作为流程的一部分，内联记录在我的经验中工作得更好。
以大多数编辑认可的forms编写文档; 对于C ++，这似乎是/ *而不是//。 这样你可以折叠它，只看到声明。
也许你会对gtk-doc感兴趣。 它可能“设置和使用有点尴尬”但你可以从源代码中获得一个很好的API文档，如下所示：
String实用程序function