在C++中创建公共头文件时，您认为最佳实践是什么？C/C++头文件文档
应该头文件包含没有，简短或大量的文件？我从几乎没有任何文档（依赖于某些外部文档）到大规格的不变量，有效参数，返回值等等，我已经看到了一切。我不确定我喜欢什么，大文档很好，因为您始终可以访问另一方面，一个带有非常简短文档的头文件通常可以在一两页文本中显示一个完整的界面，从而更好地了解可能对类进行什么操作。
比方说，我采用简短或大量的文档。我想要类似于javadoc的东西，我在那里记录返回值，参数等。在C++中最好的约定是什么？据我记得，doxygen用java doc样式的文档做了很好的事情，但是在使用javadoc样式文档之前，还有其他的约定和工具可以帮助我理解吗？
通常我把文档界面（参数，返回值，的功能是什么）在接口文件（.h）中，该文档在执行落实（函数如何一样）文件（.c，.cpp，.m）。
我在声明它之前写了一个类的概述，所以读者可以获得即时的基本信息。
我使用的工具是Doxygen。
我会definetely有一些文件中的头文件本身。它极大地提高了调试的效率，使代码旁边的信息不在单独的文档中。作为一个经验法则，我会在代码旁边记录API（返回值，参数，状态更改等）以及单独文档中的高级体系结构概述（以更全面地了解如何组合所有内容;它是很难将其与代码一起放置，因为它通常一次引用多个类）。
Doxygen从我的经验是好的。
把足够的代码放在它可以独立使用的代码中。几乎每个项目我都在文档分开的地方，它已经过时或没有完成，部分原因是如果它是一个单独的文档，它将成为一个单独的任务，部分原因在于管理层不允许它作为一项任务在预算中。作为流程的一部分，内联记录在我的经验中效果更好。
以大多数编辑认可的形式编写文档是一个块;对于C++来说，这似乎是/ *而不是//。这样你就可以折叠它并看到声明。
也许你会感兴趣gtk-doc。它可以是“有点尴尬的设置和使用”，但你可以从源代码中一个很好的API文档，看起来像这样：
我相信Doxygen的是产生文档中最常见的平台，据我所知，它或多或少能够覆盖JavaDoc标记（当然不限于此）。我已经使用了doxygen for C，结果不错，但我确实认为它更适合C++。你可能也想看看robodoc，虽然我认为Occam的Razor会告诉你宁愿去Doxygen。
关于多少文档，我从来没有一个文档粉丝本人，但我是否喜欢它，有更多的文档总是跳动没有文档。我将API文档放在头文件中，并且在实现中使用实现文档（根据理由，不是吗？）。 :)这样，IDE就有机会在autocompletion中显示它（Eclipse为JavaDocs执行此操作，例如也可能用于doxygen？），这不应该低估它。 JavaDoc有这个额外的怪癖，它使用第一个句子（即直到第一个句点）作为一个简短的描述，不知道Doxygen是否做到这一点，但如果是这样，在编写文档时应该考虑到它。
有很多文档会冒过时的风险，但是，保持文档接近代码将使人们有机会保持最新，所以你应该明确地将它保存在源代码/头文件中文件。不应该忘记的是文档的制作。是的，有些人会直接使用文档（通过IDE或其他任何方式，或者只是阅读头文件），但有些人更喜欢其他方式，因此您应该考虑将您的（定期更新的）API文档在线，所有内容都很好，可浏览，如果你的目标是基于nix的开发者，也许还会生成man文件。
这是我的两美分。