Documenting C++ static template function with Doxygen

Question

Hi i have a problem with documenting C++ class static template function with Doxygen:

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 shows:

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

and when i look at HTML output i can see that function two times:

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

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

I don't want that non-static documentation.

Any ideas how to do that?

Thanks.

I don't know about Doxygen, but you almost certainly want to define the template in the header. See http://stackoverflow.com/questions/495021. — Mike Seymour, Feb 20 '14 at 17:35
@MikeSeymour I could imagine, this might also solve doxygen's confusion here. — πάντα ῥεῖ, Feb 20 '14 at 17:38

score 1 · Answer 1 · answered May 13 '15 at 16:24

I had a similar problem with a bunch of template functions appearing twice in the documentation, once as static and once not.

I have the function definitions in an .inl file (someone prefers to use .hpp for this), which is included from the .h. I added EXTENSION_MAPPING inl=c++ to no avail. I have also tried moving the function definition to the .h to make sure that Doxygen sees it at the same time it parses the declaration, but that does not help either. This leads me to believe this is a Doxygen bug - upon parsing the member template definition, it is unable to associate it with the appropriate declaration where the static keyword appears and clumsily duplicates the function as not static. Well, parsing C++ is no easy task.

I ended up adding the .inl file to ignore list as there are no documentation comments in it anyway (except for the documentation of the @file itself). Now it does not appear in the file list but that seems like a smaller evil than having bogus member functions appear in the documentation. I suppose you could put all (or at least the problematic ones) the functions in the .inl into a #ifndef DOXYGEN block and get a perfect result.

Documenting C++ static template function with Doxygen

1 Answers1