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

Question

我希望了解在函数中是否可以添加注释（C、C++、Java），以便Doxygen可以将它们放入生成的HTML文件中。

例如：

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

- INS

---

你能否给出一个小例子，展示一下你的代码（包括注释）应该是什么样子的，以及你认为这些注释应该在文档的哪个位置显示？ - lothar

Answer 1

我不知道C语言是否可以做到，但是在Objective-C中我每天都这样做，比如我有以下注释：

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

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

渲染结果如下：

此方法执行以下操作：

• 执行操作1

• 执行操作2

---

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

据我了解和解释 Doxygen 文档，这与由 Aaron Saarela 提供的引用不矛盾。在他提供的链接开头，有一个关于内部文档的段落：

对于每个代码项，都有两种（或在某些情况下是三种）类型的描述，它们共同形成文档：简要描述和详细描述，两者都是可选的。对于方法和函数，还有第三种类型的描述，即所谓的“内部”描述，它由在方法或函数体中找到的所有注释块的串联组成。

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

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

但是算法每个步骤的详细文档可以完美地由 Doxygen 处理。

- mouviciel

---

这与Aaron上面链接的文档不符。文档可能已经过时了吗？ - Dana the Sane

据我所知，函数的文档必须放在函数体外面，但可以使用文学编程风格，将有关该函数的段落与函数体中的源代码交替排列。如果小心处理，结果在源文件和生成的文档中都易于阅读。 - RBerteig

Answer 2

不，doxygen不支持函数体内的注释块。来自手册的说明：

Doxygen允许你将文档块放在几乎任何地方（唯一的例外是函数体内或普通的C风格注释块内）。

章节：Doxygen documenting the code

- Aaron Saarela

---

谢谢。我没有注意到那个。 - INS

Answer 3

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

如果必须为用户记录，则应在函数块外部进行，在定义接口的注释上（包括签名、前置条件、后置条件、使用示例或您认为必要的任何内容）。

- David Rodríguez - dribeas

---

+1 这就是为什么我要求他举个例子，以便了解那条评论的受众可能是谁。 - lothar

这样怎么样：如果是为用户记录的，那么应该在头文件中。如果是为维护者记录的，则应该在c文件中，甚至在代码主体中。 - Michael

Answer 4

也许你可以把函数的代码作为示例放在这里。 http://www.doxygen.nl/manual/commands.html#cmdexample

- Bastien Léonard