jpa*_*ker 25 c documentation doxygen documentation-generation
我正在使用Doxygen和一些嵌入式C源代码.给定一个.c/.h文件对,你是否将Doxygen注释放在函数原型(.h文件)或函数定义(.c文件)上,还是在两个地方都复制它们？
我遇到一个问题,当我在一个地方而不是另一个地方记录时,Doxygen会警告缺少评论; 这是预期的,还是我的Doxygen搞砸了？
gim*_*mpf 18
对于公共API,我在声明中记录,因为如果不使用doxygen输出,用户通常首先查看.
我从来没有遇到只在一个地方记录的问题,但是我用它来用C++; 可能与C不同,尽管我对此表示怀疑.
[编辑]永远不要写两次.决不.源代码文档也遵循DRY,特别是关于这种复制和粘贴转换.[/ edit]
但是,您可以指定是否要为未记录的元素发出警告.虽然这些警告在理论上看起来不错,但我的经验是,它们很快就会成为一种负担,而不是一种帮助.记录所有功能通常不是可行的方法(有这样的东西是冗余文档,甚至阻碍文档,特别是太多的文档); 良好的文档需要知识渊博的人花时间.鉴于此,这些警告是不必要的.
如果你没有足够的资源来编写好的文档(金钱,时间,等等......),那些警告也无济于事.
mou*_*iel 10
引用我对这个问题的回答:C/C++头文件文档:
我把文档界面(参数,返回值,是什么在接口文件(.h)中的功能一样),并为实现(文档如何的功能一样)在实现文件(.C,的.cpp.米).我在声明之前写了课程的概述,因此读者可以立即获得基本信息.
随着Doxygen的,这意味着文档描述的概述,参数和返回值(\brief,\param,\return)用于记录函数原型和内联文档(\details)用于记录函数体(你也可以参考我回答这个问题:如何成为能够从doxygen中的函数内部提取注释吗？)