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

Question

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?

Answer 1

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;
};