使用Doxygen记录C++静态模板函数

Question

你好，我在使用Doxygen文档生成工具时遇到了一个问题：无法正确记录C++类的静态模板函数。

Clazz.h:

#ifndef CLAZZ_H
#define CLAZZ_H

/*! \file clazz.h
 *  \brief Clazz declaration
 *  \author Me and myself
 *  \sa Clazz
 */

/*! \class Clazz
 *  \brief About class
 */
class Clazz
{

public:

  /*! \fn TYPE func(TYPE value)
   *  \brief About static func
   *  \param value Parameter
   *  \returns Some value of \c TYPE
   *  \tparam TYPE Class type.
   */
  template<typedef TYPE>
  static TYPE func(TYPE value);
};

#endif

Clazz.cpp:

#include "clazz.h"

/*! \file clazz.cpp
 *  \brief Clazz implementation
 *  \author Me and myself
 *  \sa Clazz
 */

template<typedef TYPE> 
TYPE Clazz::func(TYPE value)
{
  return value;
}

Doxygen显示：

Generating docs for compound Clazz...
xxx/clazz.cpp:10: Warning: Member func(TYPE value) (function) of class Clazz is not documented.

当我查看HTML输出时，可以看到该函数出现了两次：

Public Member Functions
template<typedef TYPE> TYPE (TYPE value)

Static Public Member Functions
template<typedef TYPE> static TYPE func (TYPE value)
About func. More...

我不想要非静态文档。

有什么想法吗？

谢谢。

- Michal Steller

---

我不知道Doxygen，但你几乎肯定想在头文件中定义模板。请参见https://dev59.com/O3RB5IYBdhLWcg3w1Kr0。 - Mike Seymour

@MikeSeymour 我可以想象，这也可能解决doxygen在这里的混淆问题。 - πάντα ῥεῖ

Answer 1

我在文档中遇到了一堆模板函数出现两次的类似问题，一次是静态的，一次不是。

我将函数定义放在一个.inl文件中（有人更喜欢使用.hpp），然后从.h中引入。我尝试添加了EXTENSION_MAPPING inl=c++，但没有效果。我还尝试将函数定义移到.h中，以确保Doxygen在解析声明时同时看到它，但也没有帮助。这让我相信这是一个Doxygen的bug - 在解析成员模板定义时，它无法将其与适当的带有static关键字的声明关联起来，并且笨拙地将函数重复为非静态的。嗯，解析C++可不是一件容易的事情。

最终我将.inl文件添加到忽略列表中，因为它里面没有文档注释（除了@file本身的文档）。现在它不会出现在文件列表中，但这似乎比让虚假成员函数出现在文档中更小的问题。我想你可以将所有（或至少是有问题的）函数放入#ifndef DOXYGEN块中，从而获得完美的结果。

- the swine