6

我很想知道是否可以在函数(c、c++、java)中以 doxygen 可以将它们放在生成的 html 文件中的方式添加一些注释。

例如:

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

4 回答 4

17

我不知道 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 提供的报价并不矛盾。在他提供的链接的开头,有一段关于体内文档:

对于每个代码项,有两种(或在某些情况下为三种)类型的描述,它们共同构成文档:简要描述和详细描述,两者都是可选的。对于方法和函数,还有第三种类型的描述,即所谓的“in body”描述,它由在方法或函数的主体中找到的所有注释块的串联组成。

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

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

但是,Doxygen 可以完美地处理有关体内算法每个步骤的详细文档。

于 2009-04-16T21:58:20.283 回答
8

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

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

部分:Doxygen 记录代码

于 2009-04-16T21:30:43.393 回答
5

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

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

于 2009-04-16T21:35:49.637 回答
0

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

于 2009-04-16T21:40:15.570 回答