Question

我目前正在开始使用doxygen来记录我的源代码。我注意到语法非常繁重，每次修改源代码时，我都需要更改注释，我真的有这样的印象，即在源代码中为每个更改修改注释时要花太多时间。< / p>

您是否有一些技巧可以有效地记录我的源代码？

doxygen的某些编辑器（或现有编辑器的插件）是否存在？

自动跟踪不同步的代码/注释，并向程序员发出警告。
在源代码（模板）中为每个新项目自动添加doxygen注释格式（例如，带有参数名称的模板）

PS：我正在开发一个C / C ++项目。

Answer 1

你觉得Doxygen语法难吗？或者你现在必须评论所有的功能。

如果是前者，可能会有一种不同的工具更适合您的编码风格。请记住，Doxygen支持多种评论样式，因此请进行试验，直到找到您喜欢的样式。

如果是后者，那就强硬吧。作为一个很好的编程实践，每个面向公众的函数都应该有一个注释标题，解释：

该功能的作用
参数
返回代码
关于该功能的任何重大警告/限制。

无论您使用何种文档工具，都是如此。

我的重要提示：避免过多评论的诱惑。描述你需要什么，而不是更多。 Doxygen为您提供了大量标签，但您不必全部使用它们。

您并不总是需要@brief和详细说明。
您无需在评论中添加函数名称。
您无需评论函数原型和实现。
您不需要每个文件顶部的文件名。
您在评论中不需要版本历史记录。（您正在使用版本控制工具，对吗？）
您不需要“上次修改日期”或类似内容。

关于你的问题：当评论与代码不匹配时，Doxygen有一些配置选项可以触发警告。您可以将其集成到构建过程中，并扫描Doxygen输出以获取任何警告。这是我发现捕获代码与注释偏差的最佳方法。

Answer 2

您使用评论的方式或您的发展方式存在严重问题。

Doxygen注释用于接口上的外部/内部文档。如果您的界面变化非常快，那么您应该坐下来首先考虑架构布局。

如果您使用doxygen来记录函数的内部流程，那么您应该重新考虑这种方法（即使这样，这些注释也不会改变那么多）。当你有一个计算某个值的函数时，注释/// Calculating xy using the abc algorithm绝对不会每天都改变。

Answer 3

我觉得你收回你的评论内容，5分钟好好评论一个班级，在3个月的时间里，除了原作者以外的其他人（实际上有时是原作者）需要改变课程更少的时间来掌握。

我第二次提到David提到的文档支持，在重构参数名称时，它会在eclipse中重命名参数，例如。我不确定我是否希望它自动做任何其他事情来说实话。

“每次我修改源代码时，我还需要更改注释”可能是你的文档太多了。如果对函数的更改要求您以某种方式更改每个调用者（或者如果不实际更改，至少检查以确保它们不依赖于过时行为），则只需更改函数的文档即可您正在引入新呼叫者将依赖的新功能。所以理论上它不应该是一个巨大的开销。小的更改，如函数中的优化和错误修正，通常不需要记录。

Answer 4

这实际上取决于您在文档中提供了多少信息。

由于单元测试，我的功能现在通常较小，因此文档相应较小。此外，在记录类本身时，我总是有一小段代码来显示类应该如何使用。我发现这些是最难维护但值得的，所以你不会让小辈们在问你如何使用这门课程。

提示：

仅记录您的公共接口。
只做关于该功能的最小文档。
尝试使用支持（大多数人）或拥有插件的编辑器。

当您在6个月内编辑代码时，您会很高兴...

Answer 5

对代码的新功能和早期阶段使用非文档注释。当您发现代码已准备好发布时，您可以更新文档。还要避免重复参数或函数名称。

Answer 6

不完全是您正在搜索的内容，但此Vim plugin可以在您的定义之上生成Doxygen存根。它工作得很好。

Answer 7

判断以下风格是否符合您的需求。这是C-affine tho，但也许你可以从中汲取足够的东西。

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Answer 8

在我的专业软件体验中，每次修改源文件时，都必须输入描述更改的注释。这些更改注释通常不在Doxygen注释区域中（除非对接口进行了更改）。

我强烈建议您对代码进行评论。这不仅适用于其他人必须维护或协助您使用代码，但是当您放弃源文件一段时间（例如管理层告诉您切换项目时）它会有所帮助。我发现在编写代码时编写注释可以帮助我更好地理解算法。

Answer 9

除了Doxygen，我想你应该看看Code Rocket。

它实际上通过浏览它们包含的实际代码和注释来记录你的方法“内部”发生的事情 - 因此不仅仅局限于函数注释标题，它可能与函数内容实际上已经过时了。 / p>

它将自动为您提供方法内容的流程图和伪代码可视化，作为一种文档形式。

Answer 10

使用Doxygen的优势 - 它将生成类和方法描述而无需添加注释（只是默认情况下不设置 - 设置EXTRACT_ALL = YES）。

我没有记录每个参数，因为我认为他们的名字应该为他们做（*）。

我反对大多数人推荐的自动记录插件，因为它们会创建通用注释，然后您必须维护它们。

我希望评论有意义 - 如果我看到评论突出，我会注意。

（*）例外情况是公共代码中的接口非常稳定，有些人会从其他解释中受益，即使这样我也会尽量避免记录。

强氧，太重了维持？

10 个答案: