您认为在 C++ 中创建公共头文件时的最佳做法是什么？
头文件应该不包含、简短或大量的文档吗？我已经看到了从几乎没有文档（依赖于一些外部文档）到不变量、有效参数、返回值等的大型规范的所有内容。我不确定我到底喜欢什么，大型文档很好，因为你总是可以访问它来自您的编辑器，另一方面，带有非常简短文档的头文件通常可以在一两页文本上显示完整的界面，从而更好地概述类可以做什么。
假设我使用简短或大量文档之类的东西。我想要类似于 javadoc 的东西，我在其中记录返回值、参数等。c++ 中最好的约定是什么？据我所知，doxygen 在 java doc 样式文档方面做得很好，但是在使用 javadoc 样式文档之前我应该了解其他任何约定和工具吗？
【问题讨论】：
标签： c++ c documentation javadoc
通常我将接口的文档（参数、返回值、函数的作用）放在接口文件（.h）中，并将实现的文档（如何 em> 函数所做的）在实现文件（.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++，这似乎是 /* 而不是 //。这样你就可以折叠它，只看到声明。
【讨论】：
也许您会对gtk-doc 感兴趣。它可能“设置和使用有点尴尬”，但您可以从源代码中获得一个不错的 API 文档，如下所示：
【讨论】：