Parameter warnings and overload

Question

I would like to use the @overload special command and also have the WARN_NO_PARAMDOC Doxyfile parameter set to YES, but when I try, I get warnings from all overloaded functions that the parameters are not documented. The @overload tag works as advertised in the generated documentation, just with warnings. Am I misunderstanding the intent of the @overload command?

Specifically, the code segment that is causing problems looks like,

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);
  }
};

The resulting warnings look like this:

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

I am using Doxygen version 1.8.11 under Ubuntu 16.04

Frelling Frelling · Accepted Answer · 2017-04-04T03:02:14

Am I misunderstanding the intent of the @overload command?

The warnings are as a result of WARN_NO_PARAMDOC which will bark whenever parameters and return values are not documented. It does not ignore undocumented parameters and return values of overloaded functions that may be documented in an earlier comment block.

The purpose of @overload is to display a placeholder description and ensure that function descriptions of overloaded functions are grouped together. This is better demonstrated by the following:

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();    
};

Despite the fact that testFunction and someOther function overloads are intertwined, they are grouped together in the resulting documentation.

Parameter warnings and overload

1 Answers