Existen directrices sobre cómo las plantillas de C++ y de la plantilla de meta-funciones deben ser documentados 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 utiliza para documentar los parámetros de la plantilla.
  • @arg forma alternativa de la documentación de los parámetros de la plantilla.
  • @brief se utiliza para describir la metafunction.

Cómo debería ser la ‘volvió tipo» para la metafunction ser documentada?

¿Alguien tiene alguna buena sugerencia o preferencias personales para el uso de Doxygen con las plantillas de C++?

  • Ese es realmente un consejo útil. ¿Qué te gustaría usar, que?
  • Escribir por ti mismo en lugar de su generación. El uso de una guía de estilo y un formato consistente de curso. Código legible es una gran ventaja para la PTM como son las goteras de la abstracción. Explicar el uso de un psuedocode ayuda como la sintaxis de C++ es una mierda.
  • debe estar bromeando. Bueno docs es cuando usted nunca mirar el código. Leer explicación comentarios en un encabezado, y ni siquiera la atención ver en la aplicación, es decir, no se preocupan por un código de estilo, formato, legibilidad y lo más — esta es una buena docs. Doxygen es sólo una herramienta para la extracción de estos documentos a partir de un código fuente (idealmente de encabezados). Por supuesto, si usted desea distribuir su API descripción como un montón de «targzipped» encabezados en lugar de html/pdf/lo que sea, bueno, buena suerte; yo preferiría el uso de Doxygen.
InformationsquelleAutor mark | 2012-11-13

2 Comentarios

  1. 18

    Creo que no es posible utilizar el documento de avanzada de la plantilla de las construcciones con doxygen, ya que fue diseñado originalmente para el paradigma orientado a objetos y no metaprograming. Como una ilustración,GNU STL (libstdc++) utiliza doxygen pero hace un el pobre job de la documentación de metaprograming en la STL.

    Por otro lado, impulsar utiliza sus propias herramientas: QuickBook usos independiente archivos de texto y doxygen fuente documentada para generar BoostBook de marcado (extensión de DocBook) que se convierte en genera html/pdf. El resultado es más informativo que para libstdc++ pero, obviamente, implica un poco más de trabajo de la dev.

    Desde el impulso de la documentación es sin duda uno de los mejores para metaprograming usted podría ir por ese camino, sobre todo desde que se complementa doxygen – se puede reutilizar el marcado actual.

    Aunque no exactamente la respuesta a su pregunta, usted podría estar interesado en los últimos clang la evolución. Cuando la construcción de clang con --with-extra-options=-Wdocumentation es semánticamente comprueba su doxygen marcado con el código y genera advertencias de documentación. Te obliga a mantener docs/código sincronizado.

    • Estoy de acuerdo, la mayoría de impulso de la documentación es muy buena y sin duda tiene sentido seguir su enfoque.
    • Muy buena información aquí. El enlace a Clang/LLVM documentación de comprobación es muy útil! Tuve que usar sólo -Wdocumentation para que funcione. No es estrictamente respuesta OP pregunta, sin embargo.
    • Re «Como una ilustración,GNU STL (libstdc++) utiliza doxygen, pero hace un mal trabajo de documentar metaprograming en la STL.» GNU hace un mal trabajo de documentación, período. Mirar el código fuente. El pequeño comentario que existe es en el mejor de los pobres. No es justo usar GNU pésimo comentario como un ejemplo de los fracasos de doxygen. Un mejor ejemplo sería bien-comentó la fuente que, sin embargo, que sale en busca de mal en doxygen.
    • De hecho, el ejemplo no es la mejor, pero tengo problemas para encontrar mejores ejemplos: bibliotecas bien documentado en doxygen tienden a ser luz en las plantillas, y la plantilla pesados de las bibliotecas tienden a usar algo distinto de doxygen. Sugerencias bienvenidos!
    • Eigen, para uno. Eigen es fuertemente con plantilla. Su API es generado automáticamente por doxygen. Hace su documentación de la API de pie en su propia? Por supuesto que no. La API no es suficiente para que cualquier paquete de software de la complejidad suficiente. Pensar en el estándar de C++ biblioteca. Hay varios libros que son necesarios para describir esa biblioteca. He aquí un ejemplo de la Eigen código fuente: Matriz.h, Eigen versión 3.1.
  2. 42

    Uso @tparam para los argumentos de plantilla, @arg para los argumentos de la función. Para valores de retorno, @return. No hay regreso aquí. Hay sólo typedefs.

    IVA, el código de ejemplo no tiene el aspecto de un metafunction. Metafunctions son bestias peludas que tomar ventaja de SFINAE a hacer algo que C++ no fue pensado originalmente para hacer (por ejemplo, la reflexión). Su generate_callback_map sólo se ve como una C++03 stand-in para una plantilla typedef.

    Lo que te falta es la documentación en su typedefs y documentación sobre cómo utilizar 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;
    };
    • En C++, «metafunction» generalmente se refiere a un código como el OP. Sí, es un typedef, pero que typedef contiene el tipo que es el resultado de la evaluación del tiempo de compilación «función», precisó.
    • Me gustaría disputa que no se vuelva aquí. Formalmente las clases no tienen valores de retorno, pero lógicamente el type typedef es un retorno. Y sería mejor documentado en la documentación principal del cuerpo de la clase que como un miembro independiente.
    • Uno podría argumentar que hay un regreso aquí, en el mismo sentido, esta estructura definición es una función. Pero desde el punto de vista de Doxygen y afines/compatible doc generadores, intenta pillar algo en el ejemplo con @return sólo confunden. @el ejemplo de david typedef documentación sirve esta función y no es ambigua, pero podría ser aumentada por breve documentación sobre la estructura en sí.
    • Esta realidad debería ser seleccionado como el derecho de respuesta
    • enlace a la documentación: stack.nl/~dimitri/doxygen/manual/comandos.html#cmdtparam
    • Más reciente enlace a tparam en la documentación Doxygen: doxygen.nl/manual/commands.html#cmdtparam

Dejar respuesta

Please enter your comment!
Please enter your name here