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

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

本文关键字：参数 重载 函数 Doxygen      更新时间：2023-10-16

[编辑以提供再现问题的最小集合。]

我有类似的C++代码(文件.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)

它似乎看不到第二个和第三个函数。只有第一个出现在文档中。生成此错误需要匿名命名空间，具有相同名称的方法的类也是如此。

有人知道变通办法吗？除了更改类方法的名称，也就是…

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

我想到了Doxygen接受预处理器选项的事实，该选项可用于添加Doxygen特定的#define。这是我的doxygen.h标题：

#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，这意味着您仍然可以获得基类描述。

当您重载函数时，应该使用/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单独记录它们的

相关文章：