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

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.