参数警告和过载

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

Am I misunderstanding the intent of the @overload command?

警告是 WARN_NO_PARAMDOC 的结果，只要没有记录参数和 return 值，它就会发出警告。它不会忽略未记录的参数和 return 重载函数的值，这些值可能记录在较早的注释块中。

@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 函数重载交织在一起，但在生成的文档中将它们组合在一起。

参数警告和过载

Parameter warnings and overload

doxygen