Question

When I write class templates, and need to fully-specialize members of those classes, Doxygen doesn’t recognize the specialization – it documents only the generic definition, or (if there are only specializations) the last definition. Here’s a simple example:

===MyClass.hpp===

#ifndef MYCLASS_HPP
#define MYCLASS_HPP

template<class T> class MyClass{
public:
    static void foo();
    static const int INT_CONST;
    static const T TTYPE_CONST;
};

/* generic definitions */
template<class T>
void MyClass<T>::foo(){
    printf("Generic foo\n");
}

template<class T>
const int MyClass<T>::INT_CONST = 5;

/* specialization declarations */
template<> void MyClass<double>::foo();
template<> const int MyClass<double>::INT_CONST;
template<> const double MyClass<double>::TTYPE_CONST;
template<> const char MyClass<char>::TTYPE_CONST;

#endif

=== MyClass.cpp ===

#include "MyClass.hpp"

/* specialization definitions */
template<>
void MyClass<double>::foo(){
    printf("Specialized double foo\n");
}

template<> const int MyClass<double>::INT_CONST = 10;

template<> const double MyClass<double>::TTYPE_CONST = 3.141;
template<> const char MyClass<char>::TTYPE_CONST = 'a';

So in this case, foo() will be documented as printing “Generic foo,” INT_CONST will be documented as set to 5, with no mention of the specializations, and TTYPE_CONST will be documented as set to ‘a’, with no mention of 3.141 and no indication that ‘a’ is a specialized case.

I need to be able to document the specializations – either within the documentation for MyClass<T>, or on new pages for MyClass<double>, MyClass<char>. How do I do this? Can Doxygen even handle this? Am I possibly doing something wrong in the declarations/code structure that’s keeping Doxygen from understanding what I want?

I should note two related cases:

A) For templated functions, specialization works fine, e.g.:

/* functions that are global/in a namespace */
template<class T> void foo(){ printf("Generic foo\n"); }
template<> void foo<double>(){ printf("Specialized double foo\n"); }

This will document both foo<T>() and foo<double>().

B) If I redeclare the entire template, i.e. template<> class MyClass<double>{...};, then MyClass<double> will get its own documentation page, as a seperate class. But this means actually declaring an entirely new class – there is no relation between MyClass<T> and MyClass<double> if MyClass<double> itself is declared. So I’d have to redeclare the class and all its members, and repeat all the definitions of class members, specialized for MyClass<double>, all to make it appear as though they’re using the same template. Very awkward, feels like a kludge solution.

Suggestions? Thanks much 🙂

–Ziv

Answer 1

Further seeking indicates that this issue was an open bug, fixed in Doxygen 1.8.10.