¿Cómo documentar las plantillas de C++ y las metafunciones de plantillas con doxygen?

templates

Question

¿Hay alguna guía sobre cómo se deben documentar las plantillas C ++ y las meta-funciones de plantillas con Doxygen?

Por ejemplo:

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

Hasta ahora he visto las siguientes sugerencias:

• @tparam utilizado para documentar los parámetros de la plantilla.
• @arg forma alternativa de documentar los parámetros de la plantilla.
• @brief usado para describir la metafunción.

¿Cómo se debe documentar el ''tipo de devolución'' para la metafunción?

¿Alguien tiene buenas sugerencias o preferencias personales para usar Doxygen con plantillas C ++?

Answer 1

No creo que sea posible utilizar construcciones de plantillas avanzadas de documentos con doxygen, ya que se diseñó originalmente para el paradigma orientado a objetos y no para la metaprogramación. Como ilustración, GNU STL (libstdc ++) usa doxygen pero hace un trabajo pobre al documentar metaprogramming en el STL.

Por otro lado, boost usa sus propias herramientas: QuickBook usa archivos de texto independientes y fuente documentada de doxygen para generar el marcado de BoostBook (extensión de DocBook ) que a su vez genera html / pdf. El result es más informativo que para libstdc ++, pero obviamente implica un poco más de trabajo del desarrollador.

Dado que la documentación de impulso es sin duda una de las mejores para la metaprogramación, podría seguir esa ruta, especialmente dado que complementa a doxygen; puede reutilizar su marcado actual.

Aunque no responde exactamente su pregunta, puede que le interesen los recientes developments clang. Cuando construyes clang con --with-extra-options=-Wdocumentation , verifica semánticamente tu marcado doxygen con tu código y genera avisos de documentación. Te obliga a mantener los documentos / código sincronizados.

Answer 2

Use @tparam para los argumentos de la plantilla, @arg para los argumentos de la función. Para valores de retorno, @return . No hay retorno aquí. Solo hay typedef s.

Por cierto, su código de muestra no se ve como una metafunción. Las metafunciones son bestias peludas que aprovechan SFINAE para hacer algo que C ++ originalmente no tenía la intención de hacer (por ejemplo, reflexión). Su generate_callback_map parece a un C ++ 03 suplente para una plantilla typedef.

Lo que se está perdiendo es documentación sobre su typedefs y documentación sobre cómo usar esta plantilla.

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