参数警告和过载

Question

我想使用@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

Answer 1

我误解了@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函数重载交织在一起，它们所产生的文档中组合在一起。