¿Documentando un concepto de C++ usando doxygen?

Question

¿Existe alguna forma conveniente de documentar un concepto de C++ en doxygen? Me gustaría tener algún tipo de documentación como this in the boost documentation.

Answer 1

Lo que puede hacer es definir una etiqueta personalizada llamada Concepto, que luego puede usar como describe. Un example esto es utilizar el mecanismo de alias en Doxygen, algo así como:

ALIASES + = "con = \ xrefitem con \" Concepto \ "\ "Conceptos \""

Answer 2

Puede usar \tparam para comentar/documentar en template parameters.

Answer 3

que actualmente utilizan las páginas de manual separadas para documentar conceptos y agrupar el con \section y \subsection. Luego puedo vincularlos con \ref. Esto funciona siempre que describa conceptos con tablas como en el enlace que proporcionó, pero desafortunadamente no habilitará enlaces a secciones individuales.

También tengo un alias para crear una lista de conceptos que un tipo modela.

Answer 4

Después de algunos problemas con Doxygen, finalmente llegué a la siguiente solución.

1. definir un grupo para su concepto: el uso de páginas no es adecuada, ya que una página debe indicar sus subpáginas (de arriba a abajo del árbol), mientras que los grupos potencialmente indican muchos grupos de padres. Esto permite:

   • Adición de un concepto a una (o más) concepto (s) de los padres, sin cambiar el concepto de matriz misma (refinamiento/generalización de conceptos)
   • La vinculación de una entidad a varios conceptos, sin cambiar la concepto en sí (por ejemplo., cuando la adición de una clase a la biblioteca de la aplicación de un concepto específico)

   ejemplo

   /*!@defgroup measurement_functor_concepts Measurement function objects 
   * @ingroup generalconcepts 
   * @{ 
   * @par Description 
   * blablabla 
   * 
   * @par Notations 
   * Let @c F be the type of the function object, @c f an instance. 
   * 
   * @par Valid Expressions 
   * - @c f function object is ... 
   * - <b>f.result()</b> returns ... 
   * @} 
   */ 
   

2. Definir una comando personalizado concept con un argumento:

   ALIASES += concept{1}="@ingroup \1\n@par Implemented concepts:\n@ref \1" 
   

   El comando:

   • incluye la entidad en el grupo que define el concepto: la entidad aparecerá en la documentación del concepto (la entidad descrita en diversos grupos)
   • agrega un párrafo con Implemented concepts que proporciona un enlace al concepto implementado.

3. indicar que una clase/estructura particular, implementa el concepto:

   //!@brief Does things... 
   //!@concept{measurement_functor_concepts} 
   template <class T> 
   struct my_struct: public std::unary_function<T, void> {}; 
   

no he encontrado una manera de generar una buena documentación como en Boost (mesas buenas para la expresión válida, etc.), pero al menos esta organización de la documentación separa las cosas correctamente.

Answer 5

que sugiere considerar los siguientes:

a) Mira la documentación para el Documento de Boost Comprobación de la biblioteca. Esta documentación muestra cómo crear una clase que se pueda usar en el código para verificar que, en realidad, cumple con los requisitos del concepto que desea definir. Se utiliza de esta manera:

template<typename T> 
my_class{ 
    MyConcept(T); // provokes compile error if T does not match concept 
    T m_t; 
}; 

FYI hay una correspondencia uno a uno entre los elementos utilizados en la creación de la clase concepto de cheques y los conceptos y propuestas Lite. Entonces, cuando los conceptos lite realmente funcionan, la transición debería ser fácil.

b) Ahora use DOxygen para documentar la clase de control MyConcept !!!

c) Uso Doxygen/tparam en my_class documentación para referirse a MyConcept

c) Así que ahora tiene exactamente lo que estás pidiendo !!! - una página separada para su concepto, y la capacidad de referencia de todas las clases que requieren ese concepto.