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