如何能够从 doxygen 的函数内部提取评论？答案

【问题标题】：How to be able to extract comments from inside a function in doxygen?如何能够从 doxygen 的函数内部提取评论？
【发布时间】：2010-10-19 23:20:37
【问题描述】：

我很想知道是否可以在函数（c、c++、java）中包含一些 cmets，而 doxygen 可以将它们放入生成的 html 文件中。

例如：

function(...)
{
do_1();
/**
 * Call do_2 function for doing specific stuff.
 */ 
do_2();
}

【问题讨论】：

您能否举一个小例子说明您的代码（使用 cmets）应该是什么样子，以及您认为 cmets 应该在文档中的什么位置显示？

标签： java c++ c documentation doxygen

【解决方案1】：

我不知道 C，但我每天都在 Objective-C 中做，我有 cmet，例如：

/// This method perform the following operations:
- (void) myMethodWith: (id) anObjectArgument
{
    /// - do op1
    [self op1];

    /// - do op2
    op2(anObjectArgument);
}

呈现为：

此方法执行以下操作操作：

做op1

做op2

编辑： 在 Dana the Sane 发表评论后，关于我对 Doxygen 文档的理解以及为什么它与我的经验并不矛盾。

据我了解和解释 Doxygen 文档，这与 quote provided by Aaron Saarela 并不矛盾。在他提供的链接的开头，有一段关于体内文档：

对于每个代码项有两个（或在某些情况下，三）类型描述，它们共同构成文档：简要说明和详细说明，两者都是可选的。 对于方法和函数还有第三种类型描述，所谓的“体内” 描述，其中包括所有评论块的串联在方法的主体中找到或功能。

这意味着可以将 Doxygen 文档放在函数或方法体中。这是我在回答之上所描述的。

在我看来，Aaron 引用的段落是指通常放在函数或方法声明或实现之前的文档。这是描述参数、返回值等的一种。 heading 文档不能放在函数或方法的主体内。

但是关于体内算法每个步骤的详细文档由 Doxygen 完美处理。

【讨论】：

这与 Aaron 上面链接的文档不一致。文档可能过时了吗？
IIRC，您确实必须在函数体之外启动函数的文档，但可以使用有文字的编程风格，其中关于函数的段落通过函数体与源代码交错。小心完成，结果在源文件和生成的文档中都非常可读。

【解决方案2】：

不，doxygen 不支持函数体内的 cmets 块。来自手册：

Doxygen 允许您将文档块放在几乎任何地方（例外是在函数体内部或普通 C 样式注释块内部）。

部分：Doxygen documenting the code

【讨论】：

谢谢。我没注意到

【解决方案3】：

代码中的注释旨在解释特定的实现 sn-p 以供其他程序员理解，而不是供用户阅读的功能特性。

如果必须为用户记录，则应在功能块外在定义接口的注释上完成（签名以及前置条件、后置条件、使用示例或您认为必要的任何内容)。

【讨论】：

+1 这就是为什么我要他举个例子。查看该评论的受众可能是谁。
这个怎么样：如果它是为用户记录的，那么它应该在头文件中。如果是维护者的文档，那么它应该在 c 文件中，甚至在代码主体中。

【解决方案4】：

也许您可以将函数代码作为示例。 http://www.doxygen.nl/manual/commands.html#cmdexample

【讨论】：