Doxygen -- 多个函数的单个注释块

Posted 2023-02-21

【中文标题】Doxygen -- 多个函数的单个注释块

【英文标题】：Doxygen -- Single Comment Block for Multiple Functions

【发布时间】：2016-09-14 01:00:43

【问题描述】：

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

文件.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);

氧气输出：

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

【问题讨论】：

我很难想出一个理由来解释为什么你不单独做。为什么要为两个函数使用相同的文档？如果它们的差异不足以保证不同的描述，那么为什么它们是两个独立的功能？

@Tuffwer 够公平的。让我给你一个具体的例子。在我使用的一些库中，有一些函数可以控制特定的硬件引脚。这些函数只能在目标输出上有所不同。在模拟这些函数时，我想将它们组合在一起，它们的文档几乎是相同的。也许您希望每个文档行都不同。

嗯，这是有道理的，如果输出需要不同，因为它使用硬件而不是完全在软件中工作。在那种情况下，我会拍摄更多的混合体，并尝试用一个块来描述函数系列，但作为最终用户，我仍然认为我需要至少一行来解释特定函数的特定输出目标是什么曾是。感谢您解释您的情况，我从未处理过在硬件级别交互的代码（对于类似问题要记住的一个很好的用例），也许是时候拿起树莓派了。

@Tuffwer 我确实喜欢你的方法。到目前为止，当我尝试这样做时，基本上都没有成功。

【参考方案1】：

我不确定是否有单个评论块，但一种简洁明了的方法是使用 @copydoc (reference here)，例如：

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

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

【参考方案2】：

查看Doxygen manual 中的分组，这里有几种方法可以使用。我认为最适合这种情况的一种称为成员组。

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

///@ 
  ...
///@

或

/**@*/ 
  ... 
/**@*/

这方面的一个例子是：

/** @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 中的示例，则该示例的编译输出为 @ 987654322@，希望这是您想要的输出。

编辑：

经过测试，前一个确实对我有用，但只有当我将所需的提取模式设置为所有实体（doxyfile 中的 EXTRACT_ALL = YES）时。最好只使用实际记录的实体，因此我花了一些时间尝试与上述文档不同的方法。

文件.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);
 /** @ */

文件.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 是 on pastebin。

【讨论】：

Doxygen 告诉我：temp/file.h:18：警告：文件 file.h 的成员 fun1(int aParam)（函数）未记录。 temp/file.h:19：警告：文件 file.h 的成员 fun2(int aParam)（函数）未记录。据我所知，所有示例都处理类内部的成员函数，而不是独立函数。

稍后我会在我的机器上安装 Doxygen 并查看是否可以敲出一些东西。

@Napthali 好的，我添加了另一种似乎可以使用本质上应该是默认 Doxygen 配置的方法。让我知道这是否适合您

我还设置了 set DISTRIBUTE_GROUP_DOC 到 YES。

【参考方案3】：

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

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