C/C++头文件文档

在C++中创建公共头文件时,您认为最佳做法是什么？

头文件是否应该包含没有,简短或大量的文档？我已经看到了一切,从几乎没有文档(依靠一些外部文档),以大规格不变,有效参数,返回值等我不知道正是我喜欢的,大的文件是好的,因为你一直访问它从你的编辑器中,另一方面以非常简短的文档,头文件往往可以显示在文本给人什么是可能与类做一个更好的概述的一个或两个页面的完整接口.

假设我选择简短或大量的文档.我想要类似于javadoc的东西,其中我记录了返回值,参数等.在c ++中,最好的约定是什么？据我所知,doxygen在java doc风格的文档中做得很好,但在使用javadoc样式文档之前,我是否应该注意其他任何约定和工具？

mouviciel.. 42

通常我把文档界面(参数,返回值,是什么在接口文件中的函数一样)(.H),以及文档的实现(如何的功能一样)在实现文件(.C,的.cpp, .M).

我在声明之前写了课程的概述,因此读者可以立即获得基本信息.

我使用的工具是Doxygen.

通常我把文档界面(参数,返回值,是什么在接口文件中的函数一样)(.H),以及文档的实现(如何的功能一样)在实现文件(.C,的.cpp, .M).

我在声明之前写了课程的概述,因此读者可以立即获得基本信息.

我使用的工具是Doxygen.

我会在头文件本身中定义一些文档.它极大地改进了调试,以获得代码旁边的信息,而不是单独的文档.根据经验,我会在代码旁边记录API(返回值,参数,状态更改等),并在单独的文档中记录高级架构概述(以便更全面地了解所有内容是如何组合在一起的;它是很难将它与代码放在一起,因为它通常一次引用几个类).

根据我的经验,Doxygen很好.