我想使用 @overload 特殊命令并将 WARN_NO_PARAMDOC Doxyfile 参数设置为 YES,但是当我尝试时,我收到来自所有重载函数的警告,指出参数未记录。 @overload 标记的工作方式与生成的文档中公布的一样,只是带有警告。 我是否误解了@overload命令的意图?
具体来说,导致问题的代码段如下所示:
class ExampleClass {
public:
/// Test Function
/// @details Details on the test function API
/// @param[out] output Output parameter, by pointer
/// @param[out] optionalOutput
/// Output parameter, by pointer, nullptr if not there
/// @param[in,out] mixed Mixed use parameter, by pointer
/// @param[in] input Input parameter, by reference
/// @param[in] defaultParam Default input parameter
/// @returns Return new value
int testFunction(ExampleClass* output, ExampleClass* optionalOutput,
ExampleClass* mixed,
const ExampleClass& input, int defaultParam=1);
/// @overload
int testFunction(ExampleClass* output,
ExampleClass* mixed,
const ExampleClass& input, int defaultParam=1) {
return testFunction(output, nullptr, mixed, input, defaultParam);
}
};
生成的警告如下所示:
example_class.h:99: warning: parameters of member ExampleClass::testFunction are not (all) documented
example_class.h:99: warning: return type of member ExampleClass::testFunction is not documented
我在 Ubuntu 16.04 下使用 Doxygen 1.8.11 版本
我是否误解了@overload命令的意图?
警告是由于WARN_NO_PARAMDOC
的结果,只要参数和返回值未记录,就会吠叫。它不会忽略未记录的参数,也不会返回可能在早期注释块中记录的重载函数的值。
@overload
的目的是显示占位符说明,并确保重载函数的函数说明组合在一起。以下几点可以更好地证明这一点:
class ExampleClass {
public:
/// Test Function
/// @details Details on the test function API
/// @param[out] output Output parameter, by pointer
/// @param[out] optionalOutput
/// Output parameter, by pointer, nullptr if not there
/// @param[in,out] mixed Mixed use parameter, by pointer
/// @param[in] input Input parameter, by reference
/// @param[in] defaultParam Default input parameter
/// @return Return new value
int testFunction(ExampleClass* output, ExampleClass* optionalOutput,
ExampleClass* mixed,
const ExampleClass& input, int defaultParam=1);
/// Another function
/// @details some stuff
/// @param[out] output Output parameter, by pointer
void someOther(ExampleClass* output );
/// @overload
/// @param[out] output Output parameter, by pointer
/// @param[in,out] mixed Mixed use parameter, by pointer
/// @param[in] input Input parameter, by reference
/// @param[in] defaultParam Default input parameter
/// @return Return new value
int testFunction(ExampleClass* output,
ExampleClass* mixed,
const ExampleClass& input, int defaultParam=1);
/// @overload
/// @details some stuff
void someOther();
};
尽管testFunction
和someOther
函数重载交织在一起,但它们在生成的文档中组合在一起。