Doxygen -- 为多个函数使用单一注释块

Question

您能否使用单个注释块在doxygen中注释多个函数？下面是一个简单的示例，它不起作用。我能做类似的事情来得到我想要的吗？

file.cpp

#include file.h

/// @name FunsGroupedInDoxygen
///@{
/**
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
int fun1(int aParam) {return 0;}
int fun2(int aParam) {return 0;}
///@}

文件.h

int fun1(int aParam);
int fun2(int aParam);

Doxygen输出：

警告：文件file.h的函数成员fun2(int aParam)未被记录。

- Napthali

---

我很难想出为何您不会将它们分别处理的理由。为什么要在两个函数中使用相同的文档说明？如果它们不足以引起不同的描述，则为什么它们是两个单独的函数？ - Tuffwer

@Tuffwer 好的，让我给你举个具体的例子。在我使用的一些库中，有一些控制特定硬件引脚的函数。这些函数只能在目标输出上有所不同。在模拟这些函数时，我希望将它们分组，并且它们的文档几乎相同。也许你想让每个函数的文档行略有不同。 - Napthali

啊，这很有道理，如果输出需求因为涉及硬件而不是完全在软件中进行而需要不同的话。在这种情况下，我会尝试更多地采用混合方式，并尝试使用一个块来描述函数族，但作为最终用户，我仍然认为我至少需要一行解释特定功能的具体输出目标。 谢谢你解释你的情况，我从未处理过与硬件级别交互的代码（对于类似问题保持好的使用案例），也许现在是时候去学习树莓派了。 - Tuffwer

@Tuffwer 我很喜欢你的方法。但我迄今为止尝试过，大多数都没有成功。 - Napthali

Answer 1

在Doxygen手册中关于分组的部分，有几种方法可以使用。我认为最适合当前情况的是称为成员组的方法。

您可以使用以下两种样式定义成员组：

///@{ 
  ...
///@}

或者

/**@{*/ 
  ... 
/**@}*/

一个例子是：

/** @name FunctionGroup
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
///@{
//* fun1 specific description */
int fun1(int aParam) {return 0;}
//* fun2 specific description */
int fun2(int aParam) {return 0;}
///@}

这允许你定义一个组，为其提供通用描述，同时仍然能够在生成的Doxygen文件中对每个函数添加特定的注释。

我没有在我的计算机上安装Doxygen，因此无法直接测试此代码，但是如果遵循文档中成员组部分的group2示例，则编译输出为此处所示，希望这就是您所需的输出。

编辑：

在测试后，我发现之前的方法确实可行，但仅当我将预期的提取模式设置为所有实体（在doxyfile中EXTRACT_ALL = YES）时才有效。最好只使用实际记录的实体，因此我花了一些时间尝试以上提到的文档的不同方法。

file.h:

/**
 * \defgroup FunctionGroup A Group of Functions
 * @brief Documentation for 2 functions
 * @param aParam A Parameter
 * @retval 0 will always be returned
 * @{
 */ 
int fun1(int aParam);
int fun2(int aParam);
 /** @} */

file.cpp：

#include file.h

/** @ingroup FunctionGroup
 * @brief fun1 specific description
 */
 int fun1(int aParam){
    return 0;
 }
/** @ingroup FunctionGroup
 * @brief fun2 specific description
 */
 int fun2(int aParam){
    return 0;
 }

这是我在运行Doxygen这两个文件时得到的输出图像：

我在Windows机器上使用了doxywizard，生成了我的doxyfile，它在pastebin上。

- Tuffwer

---

Doxygen 告诉我：temp/file.h:18: 警告：文件 file.h 中的成员函数 fun1(int aParam) 没有文档记录。 temp/file.h:19: 警告：文件 file.h 中的成员函数 fun2(int aParam) 没有文档记录。据我所知，所有的示例都涉及类内部的成员函数，而不是独立的函数。 - Napthali

等我回家后，当我能够使用安装了Doxygen的机器时，我会仔细研究它，并尽力解决问题。 - Tuffwer

@Napthali 好的，我添加了另一种方式，似乎使用基本上应该是默认的Doxygen配置可以工作。如果这个方法适用于您，请告诉我。 - Tuffwer

我也将 DISTRIBUTE_GROUP_DOC 设置为 YES。 - mtvec

Answer 2

关于单个注释块，我不确定，但一种简洁易行的方法是使用@copydoc (参考这里)，例如：

/**
 * @brief Brief description
 * @param aParam A parameter
 */
void foo(int aParam) {}

/**
 * @copydoc foo(int)
 */
void bar(int aParam) {}

- sjrowlinson

Answer 3

DISTRIBUTE_GROUP_DOC选项具有您想要的效果。全局启用相对无害，即使设置了HIDE_UNDOC_MEMBERS，成员组中未记录的成员也仅会出现在页面的摘要表中。

请注意，“成员子组”适用于\defgroup组以及类和命名空间。

- Davis Herring