用于记录具有可变参数的重载函数的氧

Doxygen for documenting overloaded functions with variable parameters

本文关键字：重载 函数 参数 变参 记录 用于      更新时间：2023-10-16

是否有可能为这样的代码创建适当的文档:

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

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

如果将参数指定为…它会被氧吸收。例如:param[in] ... Arguments for format specification。这将正确地出现在您生成的文档中。

没有关于const char*和const wchar_t*消歧的线索。

如果您启用AUTOLINK_SUPPORT，默认情况下已经启用，它应该在没有包括ref的情况下工作。也就是说，氧看到的东西可能是可链接的名称，并试图找出他们为你没有你显式地称他们为引用。我刚刚测试了一个例子:

/// 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我使用氧(version 1.86)的c++，但我没有任何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参数。虽然它可能看起来像这里写的一大堆乱七八糟的文本，但通过氧运行将使它更清晰，并且(在我看来)对于您的代码/文档的一些用户来说非常可读。

相关文章：