C/C++；头文件文档 < C++ > 中创建公头文件时，您认为最好的做法是什么？

头文件是否应该不包含、简短或大量文档？从几乎没有文档（依赖于一些外部文档）到不变量、有效参数、返回值等的大型规范，我都见过。我不确定我到底喜欢什么，大型文档很好，因为您总是从编辑器访问它，另一方面，具有非常简短文档的头文件通常可以在一到两页文本上显示完整的接口，从而更好地概述类的功能

比如说，我使用了一些简短或大量的文档。我想要一些类似JavaDoc的文档，其中我记录返回值、参数等等。C++中最好的约定是什么？据我所知，doxygen在java文档风格的文档方面做得很好，但是在使用java文档风格的文档之前，我是否应该了解其他的约定和工具

我肯定会在头文件中有一些文档。将信息放在代码旁边，而不是放在单独的文档中，这大大改进了调试。根据经验，我会在代码旁边记录API（返回值、参数、状态更改等），并在单独的文档中记录高级体系结构概述（以便更广泛地了解所有内容是如何组合在一起的；很难将其与代码放在一起，因为它通常一次引用多个类）

根据我的经验，强氧是好的

---

在代码中加入足够的内容，使其能够独立运行。我参与过的几乎每个项目都有单独的文档，文档过时或未完成，部分原因是如果是单独的文档，它将成为一项单独的任务，部分原因是管理层不允许它作为预算中的任务。根据我的经验，将内联文档作为流程的一部分工作得更好

---

以大多数编辑认为是块的形式编写文档；对于C++，这似乎是/*而不是/ /。这样，您可以折叠它，只需查看声明

通常我会将接口文档（参数、返回值、函数的作用）放在接口文件（.h）中，将实现文档（函数的作用方式）放在实现文件（.c、.cpp、.m）中

我在类声明之前写了一个类的概述，这样读者就可以立即获得基本信息

---

我使用的工具是Doxygen。

也许您会感兴趣。它可能“设置和使用起来有点笨拙”，但您可以从源代码中获得一个很好的API文档，如下所示：

---

我相信Doxygen是生成文档最常用的平台，据我所知，它或多或少能够涵盖JavaDoc表示法（当然不限于此）。我已经使用了DoxGEY作为C，OK结果，我认为它更适合C++。你可能也想研究一下机器人世界，尽管我认为奥卡姆的剃须刀会告诉你更喜欢强氧

关于有多少文档，我自己从来都不是一个文档迷，但不管我喜欢与否，拥有更多文档总比没有文档要好。我会将API文档放在头文件中，将实现文档放在实现中（很合理，不是吗？）：这样，IDE就有机会在自动完成过程中获取并显示它（例如，Eclipse为JavaDocs这样做，可能也为doxygen？），这一点不应被低估。JavaDoc还有一个额外的怪癖，它使用第一句话（即直到第一个句号）作为简要描述，但不知道Doxygen是否这样做，但如果是这样，在编写文档时应该考虑到这一点

拥有大量文档有过时的风险，但是，将文档与代码放在一起会使人们有机会保持文档的最新状态，因此您应该明确地将其保存在源/头文件中。但不应该忘记的是文档的制作。是的，有些人会直接使用文档（通过IDE或任何东西，或者只是读取头文件），但是有些人喜欢其他方式，所以你应该考虑把你的（经常更新的）API文档放在网上，它们都是好的和可浏览的，如果您的目标是基于*nix的开发人员，还可以生成man文件

那是我的两分钱