Tag: 文档

扫描代码注释的工具，并转换为标准格式

我正在研究一个已经看到许多不同作者和许多不同文档样式的C项目。 我是doxygen和其他文档生成工具的忠实粉丝，我想迁移这个项目以使用其中一个系统。 是否有人知道可以扫描源代码注释的工具，如“描述”，“作者”，“文件名”和其他类型的上下文，以智能地将注释转换为标准格式？ 如果不是，我想我可以写一个疯狂的脚本，或手动转换。 谢谢

评论C代码，标题和源文件

我正在寻找记录我的C代码的“最佳实践”。 就像在任何项目中一样，我有一些头文件“.h”和相应的源文件“.c” 在头文件中你放了什么样的评论？ 在源文件中？ 问题出现了，因为我评论了我的头文件，c文件看起来像一团糟。 保持代码评论良好的最佳做法是什么？

使用Doxygen与C，您是否评论函数原型或定义？ 或两者？

我正在使用Doxygen和一些嵌入式C源代码。 给定一个.c / .h文件对，你是否将Doxygen注释放在函数原型（.h文件）或函数定义（.c文件）上，还是在两个地方复制它们？ 我遇到一个问题，当我在一个地方而不是另一个地方进行记录时，Doxygen会警告缺少评论; 这是预期的，还是我的Doxygen搞砸了？

C / C ++头文件文档

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