如何从doxygen中的函数内部提取注释？

Question

我很想知道是否有可能在函数(c,c ++,java)中有一些注释,doxygen可以将它们放在生成的html文件中.

例如:

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

Answer 1

我不知道C,但我每天都在Objective-C中做,我的评论如下:

/// 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文档,这与Aaron Saarela提供的引用并不矛盾.在他提供的链接的开头,有一个关于体内文件的段落:

对于每个代码项,有两种(或在某些情况下为三种)描述类型,它们一起形成文档:简要描述和详细描述,两者都是可选的.对于方法和函数,还存在第三种类型的描述,即所谓的"体内"描述,其包括在方法或函数的主体内找到的所有注释块的串联.

这意味着可以将Doxygen文档放在函数或方法体中.这就是我在答案中所描述的内容.

在我看来,Aaron引用的段落指的是通常放在功能或方法声明或实现之前的文档.这是描述参数,返回值等的那个.该标题文档不能放在函数或方法的主体内.

但是关于身体内部算法的每个步骤的详细文档完全由Doxygen处理.

Answer 2

不,doxygen不支持函数体内的注释块.从手册:

Doxygen允许您将文档块放在几乎任何位置(异常位于函数体内或普通C样式注释块内).

部分:Doxygen记录代码

Answer 3

代码中的注释旨在解释另一个程序员要理解的特定实现代码段,而不是用户阅读的功能特性.

如果它必须证明对于用户来说,它应该做ouside的功能块,在定义接口(签名以及先决条件,后置条件,用法示例或任何你认为必要的)评论.