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 typedef
s.
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; };
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With