Doxygen complains about overloaded functions that take same template but with different template parameter

Question

[Edited to provide a minimal set to reproduce the issue.]

I have C++ code similar to this (file.h):

namespace xxx {
  template< typename T >
  class Array {};

  using sint = std::ptrdiff_t;
  using uint = std::size_t;
  using dfloat = double;
  using IntegerArray = Array< xxx::sint >;
  using UnsignedArray = Array< xxx::uint >;
  using FloatArray = Array< xxx::dfloat >;
}

/// \brief A namespace
namespace yyy {
namespace {

  /// \brief A function
  inline out* function( xxx::UnsignedArray const& in ) {}

  /// \brief A function
  inline out* function( xxx::IntegerArray const& in ) {}

  /// \brief A function
  inline out* function( xxx::FloatArray const& in ) {}

  /// \brief A class
  class AAA {
    public:
      /// \brief A class method
      out* function( xxx::BBB const& bbb ) {}
};
}}

The Doxyfile is:

OUTPUT_DIRECTORY       = out
EXTRACT_ANON_NSPACES   = YES
INPUT                  = .
FILE_PATTERNS          = *.h

Doxygen complains with:

Searching for member function documentation...
/Users/cris/tmp/doxygenissue/file.h:25: warning: no matching class member found for 
  out *anonymous_namespace file yyy::anonymous_namespace{file.h}::yyy::h::function(xxx::IntegerArray const &in)

/Users/cris/tmp/doxygenissue/file.h:28: warning: no matching class member found for 
  out *anonymous_namespace file yyy::anonymous_namespace{file.h}::yyy::h::function(xxx::FloatArray const &in)

It doesn't seem to see the 2nd and 3rd functions. Only the first one shows up in the documentation. The anonymous namespace is needed to generate this error, as is the class with a method with the identical name.

Does anybody know a workaround? Besides changing the name of the class method, that is...

Answer 1

I found a rather ugly way to make it work until the bug gets fixed in Doxygen. It seems to work at least for my case. I suppose it affects some links, though, but at this point I think I prefer to get the expected description for each function than having proper links and namespace names.

I thought about the fact that Doxygen accepts preprocessor options which can be used to add a Doxygen specific #define. Here is my doxygen.h header:

#ifndef DOXYGEN_HPP
#define DOXYGEN_HPP

#ifdef DOXYGEN
#define no_name             doxygen
#else
#define no_name
#endif

#endif

As we can see, I defined a macro named no_name and when I compile with Doxygen I set it to doxygen otherwise it remains empty.

Now in my C++ files I do:

...
namespace no_name
{
    // static code goes here
    ...
} // no name namespace
...

So now when compiling with g++, I don't get a name as expected. When compiling with Doxygen, however, the namespace is given a name: doxygen and I do not get that error anymore.

For this magic to work, you also need to tweak your doxy file. Here are the relevant options:

MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = DOXYGEN=1
EXPAND_AS_DEFINED      = no_name

You may also need to fix the include path. It will be very important that the doxygen.h file gets included. I have CMake so it's easy for me:

INCLUDE_PATH           = @CMAKE_SOURCE_DIR@

At this point I've not seen anything breaking badly. So I am guessing it's a nice intermediate solution.

One other thing, make sure that INHERIT_DOCS is NO because by default it's YES and that means you'd still get the base class description.

Answer 2

As you are overloading a function, you should use /overload keyword , to add documentation for overloaded function.

template<typename T> class Array;
using UnsignedArray = Array<unsigned>
using IntegerArray = Array<int>
using FloatArray = Array<float>

 /// \overload brief A function
void function(UnsignedArray const&);

/// \overload brief A function
void function(IntegerArray const&);

/// \overload brief A function
 void function(FloatArray const&);

This will help doxygen to separately document them