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

>头文件是否应包含没有,简短或大量的文档？我已经看到了从几乎没有文档(依赖于一些外部文档)到大规格的不变量,有效参数,返回值等的所有内容.我不确定我更喜欢什么,大文档很好,因为你总是访问它来自您的编辑器,另一方面,带有非常简短文档的头文件通常可以在一页或两页文本上显示完整的界面,从而可以更好地概述可以对类进行的操作.
>假设我选择简短或大量的文档.我想要一些类似于javadoc的东西,其中我记录了返回值,参数等.在c中,最好的约定是什么？据我所知,doxygen在java doc风格的文档中做得很好,但在使用javadoc样式文档之前,我是否应该注意其他任何约定和工具？

解决方法:

通常我在接口文件(.h)中放置接口的文档(参数,返回值,函数的作用),以及实现文件中的实现文档(函数如何)(.c,.cpp, .M).

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

我使用的工具是Doxygen.