Comment documenter les modèles c ++ et leurs métafonctions avec doxygen

Question

Existe-il des lignes directrices sur la façon dont les modèles c++ et le modèle de méta-fonctions doivent être documentées avec doxygen.

par exemple

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

Pour l'instant j'ai vu les suggestions suivantes:

• @tparam utilisé pour documenter les paramètres du modèle.
• @arg autre façon de documenter les paramètres du modèle.
• @brief utilisé pour décrire la metafunction.

Comment le "retourné type" pour le metafunction être documentées?

Quelqu'un a une bonne suggestions ou des préférences personnelles pour Doxygen avec les modèles C++?

Answer 1

Utiliser @tparam arguments de modèle, @arg pour les arguments des fonctions. Pour les valeurs de retour, @return. Il n'y a pas de retour ici. Il y a juste typedefs.

BTW, votre exemple de code ne ressemble pas à un metafunction. Metafunctions sont bêtes poilues qui profitent de SFINAE de faire quelque chose que le C++ n'était pas à l'origine prévu pour (par exemple, la réflexion). Votre generate_callback_map ressemble à un C++03 stand-in pour un modèle de définition de type.

Ce qui vous manque est la documentation sur votre typedefs et de la documentation sur la façon d'utiliser ce modèle.

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

Answer 2

Je ne pense pas qu'il est possible d'utiliser le document avancé modèle construit avec doxygen depuis qu'il a été conçu à l'origine pour le paradigme orienté objet et pas metaprograming. Comme une illustration,GNU STL (libstdc++) utilise doxygen mais fait un mauvais travail de documentation metaprograming dans la STL.

D'autre part, de stimuler l'utilise ses propres outils: QuickBook utilise autonome des fichiers texte et doxygen documenté source pour générer BoostBook de balisage (extension de DocBook) qui à son tour génère du code html/format pdf. Le résultat est plus instructif que de libstdc++ mais, évidemment, implique un peu plus de travail de la dev.

Depuis stimuler la documentation est sans doute l'un des meilleurs pour metaprograming vous pourriez aller dans cette voie, surtout depuis qu'il complète doxygen - vous pouvez réutiliser votre balisage existant.

Même si elle ne correspond pas exactement la réponse à votre question, vous pourriez être intéressé au cours des dernières clang développements. Lors de la construction de clang avec --with-extra-options=-Wdocumentation il sémantiquement vérifie votre doxygen balisage avec votre code et génère la documentation des avertissements. Vous oblige à garder docs/code synchronisé.