How to document C++ templates and template metafunctions with doxygen?

Are there any guidelines on how C++ templates and template meta-functions should be documented with Doxygen?

For example:

/// @brief metafunction for generation of a map of message types to
/// their associated callbacks.
/// @tparam Seq the list of message types
template< class Seq >
struct generate_callback_map
{
    typedef typename mpl::transform< Seq
                                   , build_type_signature_pair< mpl::_1 > 
                                   >::type vector_pair_type;
    typedef typename fusion::result_of::as_map< vector_pair_type >::type type;
};

So far I have seen the following suggestions:

• @tparam used to document template parameters.
• @arg alternative way of documenting template parameters.
• @brief used to describe the metafunction.

How should the 'returned type' for the metafunction be documented?

Does anyone have any good suggestions or personal preferences for using Doxygen with C++ templates?

Use @tparam for template arguments, @arg for function arguments. For return values, @return. There is no return here. There are just typedefs.

BTW, your sample code doesn't look like a metafunction. Metafunctions are hairy beasts that take advantage of SFINAE to do something that C++ wasn't originally intended to do (e.g., reflection). Your generate_callback_map just looks like a C++03 stand-in for a template typedef.

What you are missing is documentation on your typedefs and documentation on how to use this template.

/// @brief metafunction for generation of a map of message types to
/// their associated callbacks.
/// @details
/// Usage: Use <tt>generate_callback_map<Type>::type</tt> to ...
/// @tparam Seq the list of message types
/// 
template< class Seq >
struct generate_callback_map
{
  /// @brief It's a good idea to document all of your typedefs.
  typedef typename mpl::transform< Seq
                                 , build_type_signature_pair< mpl::_1 > 
                                 >::type vector_pair_type;

  /// @brief This is why generate_callback_map exists. Document it!
  typedef typename fusion::result_of::as_map< vector_pair_type >::type type;
};

I don't think it is possible use document advanced template constructs with doxygen since it was originally designed for the object oriented paradigm and not metaprograming. As an illustration,GNU STL (libstdc++) uses doxygen but does a poor job of documenting metaprograming in the STL.

On the other hand, boost uses its own tools: QuickBook uses standalone text files and doxygen documented source to generate BoostBook markup (extension of DocBook) which in turns generates html/pdf. The result is more informative than for libstdc++ but obviously involves a little more work from the dev.

Since boost documentation is arguably one of the best for metaprograming you could go that route, especially since it complements doxygen - you can reuse your existing markup.

Although it does not exactly answer your question, you might be interested in recent clang developments. When building clang with --with-extra-options=-Wdocumentation it semantically checks your doxygen markup with your code and generates documentation warnings. Forces you to keep docs/code synchronized.