web-dev-qa-db-fra.com

Comment documenter les modèles C ++ et les métafonctions de modèle avec doxygen?

Existe-t-il des directives sur la façon dont les modèles C++ et les méta-fonctions des modèles doivent être documentés 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;
};

Jusqu'à présent, j'ai vu les suggestions suivantes:

  • @tparam utilisé pour documenter les paramètres du modèle.
  • @arg autre moyen de documenter les paramètres du modèle.
  • @brief utilisé pour décrire la métafonction.

Comment le "type retourné" pour la métafonction doit-il être documenté?

Quelqu'un a-t-il de bonnes suggestions ou des préférences personnelles pour utiliser Doxygen avec des modèles C++?

c++templatesdoxygen
51
mark

Je ne pense pas qu'il soit possible d'utiliser des constructions de modèles de document avancées avec doxygen car il a été initialement conçu pour le paradigme orienté objet et non pour la métaprogrammation. À titre d'illustration, GNU STL (libstdc ++) utilise doxygen mais fait un mauvais travail de documenter la métaprogrammation dans la STL.

D'autre part, boost utilise ses propres outils: QuickBook utilise des fichiers texte autonomes et une source documentée doxygen pour générer BoostBook balisage (extension de DocBook ) qui à son tour génère html/pdf. Le résultat est plus informatif que pour libstdc ++ mais implique évidemment un peu plus de travail du développeur.

Étant donné que la documentation de boost est sans doute l'une des meilleures pour la métaprogrammation, vous pouvez emprunter cette voie, d'autant plus qu'elle complète doxygen - vous pouvez réutiliser votre balisage existant.

Bien qu'il ne réponde pas exactement à votre question, vous pourriez être intéressé par le récent clang développements . Lors de la construction de clang avec --with-extra-options=-Wdocumentation il vérifie sémantiquement votre balisage doxygen avec votre code et génère des avertissements de documentation. Vous oblige à garder les documents/codes synchronisés.

19
Antoine

Utilisation @tparam pour les arguments de modèle, @arg pour les arguments de fonction. Pour les valeurs de retour, @return. Il n'y a pas de retour ici. Il n'y a que typedefs.

BTW, votre exemple de code ne ressemble pas à une métafonction. Les métafonctions sont des bêtes velues qui profitent de SFINAE pour faire quelque chose que C++ n'était pas censé faire à l'origine (par exemple, la réflexion). Votre generate_callback_map ressemble juste à un remplaçant C++ 03 pour un typedef de modèle.

Ce qui vous manque, c'est de la documentation sur vos typedefs et de la documentation sur l'utilisation de 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;
};
44
David Hammen