Doxygen etiqueta copydoc para reutilizar ejemplos de código

Question

Quiero reutilizar un bloque de código de ejemplo con la etiqueta \ copydoc.

Para explicar el problema. Digamos que tengo dos funciones documentadas:

/** Aquires resource. */ 
Resource* AquireResource(int id); 

/** Releases resource.*/ 
void ReleaseResource(Resource* res); 

En muchos casos, quiero poner en un pequeño ejemplo de código de cómo utilizar la función en un contexto, que a menudo implica el uso de una amplia gama de funciones que todos sean suficientemente representado por el mismo ejemplo de código, por ejemplo:

/** Aquires resource. 
* 
* \par Example: 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/ 
Resource* AquireResource(int id); 

/** Releases resource. 
* 
* \par Example: 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/ 
void ReleaseResource(Resource* res); 

Así que el ejemplo del código está duplicado, no es bueno. Deseo utilizar copydoc, algo como esto:

/** \page ResourceExampleTag 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/  

/** Aquires resource. 
* 
* \par Example: 
* \copydoc ResourceExampleTag 
*/ 
Resource* AquireResource(int id); 

/** Releases resource. 
* 
* \par Example: 
* \copydoc ResourceExampleTag 
*/ 
void ReleaseResource(Resource* res); 

I.e. ejemplo de código en un lugar, reutilizado en otros lugares.

Esto es en realidad lo que he conseguido, pero no estoy satisfecho con él ya que no sé cómo ocultar la página ficticia 'ResourceExampleTag' que estoy creando para copiar. Entonces, en algún lugar de la documentación resultante, hay una página con algún código completamente fuera de contexto. Por lo que puedo ver, lo que hay que hacer aquí es encontrar una etiqueta a la que copydoc pueda hacer referencia y que no represente ningún contenido en sí mismo. Sin embargo, esa es mi línea de pensamiento, podría haber otras mucho mejores.

También puedo mencionar que (por varias razones no me molestaré en entrar) no deseo utilizar la etiqueta \ example con archivos de código de ejemplo externos.

Gracias.

Answer 1

que he encontrado el comando @snippet sea más útil para crear ejemplos en línea como si estuvieras tratando de hacer Básicamente tengo un archivo de origen de mis ejemplos, my_examples.cpp

/// [exampleMyFirst] 
void foo(void) 
{ 
    Resource* foo = AquireResource(42); 
    ReleaseResource(foo); 
    foo = nullptr; //Or NULL 
} 
/// [exampleMyFirst] 

/// [exampleTwo] 
void bar(void) 
{ 
    std::cout << "Unrelated to my first example." << std::endl; 
} 
/// [exampleTwo] 

A continuación, en el bloque de documentación doxygen para su uso @snippet función a utilizar el ejemplo.

/// Aquires resource. 
/// 
/// @par Example: 
/// @snippet my_examples.cpp exampleMyFirst 
Resource* AquireResource(int id); 

... Y por supuesto, sólo después de terminar la respuesta, me doy cuenta de que no desea utilizar un archivo externo, pero desde que me topé con la cuestión tratando de hacer lo que he descrito aquí, podría ser útil para alguien!

Answer 2

Tuve el mismo problema y tampoco pude encontrar ninguna solución elegante. Finalmente me encontré con lo siguiente:

1) En alguna página al azar, enlace en nueva subpágina llamada Oculto

/*! \mainpage My MainPage 
    blah blah blah 
    \subpage Hidden 
    */ 

2) Crear la página oculta, que une a tu ejemplo 'maniquí' temas. Nombre a la página  

/*! \page Hidden   
    \subpage MyExample 
    */ 

3) Ahora se puede \copydoc MyExample donde quiera, y es invisible para los usuarios del HTML generado por Doxygen.

Answer 3

Esto funciona para mí:

class MyClass 
{ 
    public: 
    /** 
    * @class hide_commonstuff 
    * @par Example: 
    * @code 
    * The common example 
    * @endcode 
    */ 

    /** 
    * First function. 
    * 
    * @copydoc hide_commonstuff 
    */ 
    void first(); 

    /** 
    * Second function. 
    * 
    * @copydoc hide_commonstuff 
    */ 
    void second(); 
}; 

y luego en la configuración Doxygen se establece EXCLUDE_SYMBOLS = hide_*

La documentación se copia de la hide_commonstuff pero esta clase no se muestra en la lista de clase.

También: es necesario que haya una línea en blanco antes @copydoc o de lo contrario no funciona (a veces, no siempre ...)