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