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