Doxygen 抱怨采用相同模板但具有不同模板参数的重载函数

Question

[编辑以提供最小集来重现该问题。]

我有与此类似的 C++ 代码 (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 ) {}
};
}}

Doxyfile 是：

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

Doxygen 抱怨：

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)

好像没有看到第二个和第三个功能。只有第一个出现在文档中。需要匿名命名空间来生成此错误，class 和具有相同名称的方法也是如此。

有人知道解决方法吗？除了更改 class 方法的名称，即...

Answer 1

当您重载函数时，您应该使用 /overload 关键字来为重载函数添加文档。

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

这将有助于 doxygen 单独记录它们

Answer 2

我发现了一种相当丑陋的方法来让它工作，直到错误在 Doxygen 中得到修复。它似乎至少对我的情况有效。不过，我想它会影响一些链接，但在这一点上，我认为我更愿意获得每个函数的预期描述，而不是拥有正确的链接和命名空间名称。

我想到了 Doxygen 接受可用于添加 Doxygen 特定 #define 的预处理器选项这一事实。这是我的 doxygen.h header:

#ifndef DOXYGEN_HPP
#define DOXYGEN_HPP

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

#endif

正如我们所见，我定义了一个名为 no_name 的宏，当我使用 Doxygen 编译时，我将其设置为 doxygen 否则它保持为空。

现在在我的 C++ 文件中我这样做：

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

所以现在用 g++ 编译时，我没有得到预期的名称。然而，当使用 Doxygen 编译时，命名空间被赋予了一个名称：doxygen 并且我不再收到该错误。

要让这个魔法发挥作用，您还需要调整您的 doxy 文件。以下是相关选项：

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

您可能还需要修复包含路径。包含 doxygen.h 文件非常重要。我有 CMake，所以对我来说很简单：

INCLUDE_PATH           = @CMAKE_SOURCE_DIR@

目前我还没有看到任何严重损坏的情况。所以我猜这是一个很好的中间解决方案。

另一件事，请确保 INHERIT_DOCS 是 NO，因为默认情况下它是 YES，这意味着您仍然会得到基本的 class 描述。

Doxygen 抱怨采用相同模板但具有不同模板参数的重载函数

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

c++

doxygen