Doxygen 用于记录具有可变参数的重载函数答案

【问题标题】：Doxygen for documenting overloaded functions with variable parametersDoxygen 用于记录具有可变参数的重载函数
【发布时间】：2014-07-15 02:01:59
【问题描述】：

是否可以让 doxygen 为这样的代码创建适当的文档：

void Print(const char* pszFormat, ...);
void Print(const wchar_t* pszFormat, ...);

这段代码有两个问题。首先，我不能从我的代码的其他部分引用这两个函数。对于 \ref Print(const char*, ...); 和 \ref Print(const wchar_t*, ...); 的链接仅生成上述声明之一。

变量参数也以必须描述的预定义格式放置。尝试使用 '\param' 标记会导致在函数声明中找不到有关参数的警告。由于我有多个这样的功能，如果可能的话，我想摆脱专门针对这种情况的警告。

提前致谢。

【问题讨论】：

标签： c++ doxygen variadic-functions overloading

【解决方案1】：

如果您将参数按字面意思指定为 ...，它将被 Doxygen 拾取。例如。如下：\param[in] ... Arguments for format specification。这将正确显示在您生成的文档中。

不过，对于 const char* 和 const wchar_t* 的消歧没有任何线索。

【讨论】：

【解决方案2】：

如果您启用AUTOLINK_SUPPORT（默认情况下已启用），它应该不工作，包括\ref。那就是 - Doxygen 看到可能是可链接名称的东西，并试图为您找出它们，而无需您明确称它们为引用。我只是测试了一个例子：

/// Get 8 bits of foo
/// @param blah The blah to foo
void getFoo(uint8_t blah) = 0;

/// Get 16 bits of foo
/// @param blah The blah to foo
void getFoo(uint16_t blah) = 0;

/// First, look at getFoo(uint8_t) for info,
/// then look at getFoo(uint16_t) for more
void getBar() = 0;

getBar() 文档中创建的两个链接指向各自的功能。

FWIW 我在 C++ 中使用 doxygen (version 1.86)，但我没有打开任何 C 或 C++ 优化，我启用了 JAVA_DOC 和 QT，所以我不这么认为如果您的示例是 C++ 或 Java，这应该很重要，但我并不肯定。

至于您的第二个问题，首先想到的是使用代码块来显示变量参数应该是什么，但我不知道这是否足以满足您的需求。例如

/// Bar some foos with extra arguments
/// @param foo The foo we totally want to bar
/// @return true if we barred
/// Typical usage requires that we either supply the number of times to bar
///  followed by some other baz ...
/// @code
/// uint8_t nbars = 12; // must be uint8_t because of some reason
/// Baz baz = new Baz(); // or some old Baz lying around, doesn't matter
/// bool isBarred = bar(foo, nbars, baz);
/// @code
/// ... OR, we need to supply a list of Baz's, so we know what to do
/// @code
/// Baz manyBaz[]; 
/// // fill in manyBaz with whatever Baz's you want
/// bool isBarred - bar(foo, manyBaz);
/// @code
bool bar(foo, ...);

通过这种方式，您的文档将尽可能清晰地表达出来，而无需实际求助于每个都可以具有显式 @param 参数的多态（非可变）函数。虽然它可能看起来像是在这里写的一大堆文本，但通过 doxygen 运行它会使其更清晰，并且（在我看来）对于您的代码/文档的某些用户来说非常易读。

【讨论】：