¿Cómo puedo incluir un subconjunto de un archivo .cpp en un comentario de Doxygen?

Question

Estoy intentando escribir algunos bloques de comentarios de Doxygen, y me gustaría incluir ejemplos de fragmentos de código. Por supuesto, me gustaría que los ejemplos compilaran para que no se vuelvan obsoletos.

Mi example.cpp (que \ include en el archivo .h) tiene el siguiente aspecto:

#include "stdafx.h" 

#include "../types_lib/Time_Limiter.h" 
#include <vector> 

void tl_demo() { 
    // scarce will be a gate to control some resource that shouldn't get called 
    // more than 10 times a second 
    Time_Limiter scarce (10); 

    // here's a bunch of requests 
    std::vector<int> req (500); 

    for (size_t i=0;i<req.size();i++) { 
     scarce.tick(); 
     // once we get here, we know that we haven't ticked 
     // more than 10 times in the last second. 

     // do something interesting with req[i] 
    } 
} 

// endcode 

y mi archivo de cabecera (que estoy corriendo Doxygen) tiene el siguiente aspecto:

/** 
* \ingroup types_lib 
* 
* \class Time_Limiter 
* 
* \brief Thread safe gate used to control a resource (such as an internet quote service) that has a limit on how often you can call it. 
* 
* \dontinclude Time_Limiter_example.cpp 
* \skipline void 
* \until endcode 
* 
**/ 

Y me gustaría hacer que doxygen simplemente incluya cosas comenzando en "void demo" hasta el final del archivo (pero sin // código final).

He intentado experimentar con \ dontinclude y \ skip, \ skipline, y \ hasta, y no puedo entender los encantamientos correctos.

EDITAR: incluye mi archivo .h, y ahora casi tengo el hechizo correcto. Esto hace que sea casi exactamente lo que quiero, ¿hay alguna forma de usar \ hasta que no tenga una etiqueta, y deshacerme de esa última // línea de código final de example.cpp?

Answer 1

Editado para añadir el 2º argumento de clip de macro.

Esto es lo que he hecho, que parece funcionar para mí. Sobre todo tomada de pista de EricM ....

mi archivo de origen Time_Limiter_example.cpp es:

#include "stdafx.h" 

#include "../types_lib/Time_Limiter.h" 
#include <vector> 

void tl_demo() { 
    // scarce will be a gate to control some resource that shouldn't get called 
    // more than 10 times a second 
    Time_Limiter scarce (10); 

    // here's a bunch of requests 
    std::vector<int> req (500); 

    for (size_t i=0;i<req.size();i++) { 
     scarce.tick(); 
     // once we get here, we know that we haven't ticked 
     // more than 10 times in the last second. 

     // do something interesting with req[i] 
    } 
} // endcode 

void tl_demo_short() 
{ 
} //endcode 

Y quiero incluir, pero no tienen los #includes en la parte superior.

que define un alias en mi Doxyfile como:

ALIASES += clip{2}="\dontinclude \1 \n \skipline \2 \n \until endcode" 

Y en mi cabecera, mi comentario es el siguiente:

/** 
* \ingroup types_lib 
* 
* \class Time_Limiter 
* 
* \brief Thread safe gate used to control a resource (such as an internet quote service) that has a limit on how often you can call it. 
* 
* \clip{Time_Limiter_example.cpp,tl_demo} 
**/ 

Y eso es exactamente lo que quiero, que incluye sólo la Funciton tl_demo() desde el archivo .cpp.

Answer 2

Creo que \verbinclude debería permitirle incluir un archivo como código y no tener que poner // \endcode en la última línea.

EDITAR: Le sugiero que ponga el código que desea incluir en su propio archivo de inclusión y use #include en el archivo CPP y luego use \verbinclude en el archivo de encabezado doxygen.

archivo de origen que se vería así:

#include "stdafx.h" 
#include "../types_lib/Time_Limiter.h" 
#include <vector>  
#include "Time_Limiter_example.inc" 

El archivo "Time_Limiter_example.inc", entonces puede contener sólo el ejemplo de código:

void tl_demo() { 
    // scarce will be a gate to control some resource that shouldn't get called 
    // more than 10 times a second 
    Time_Limiter scarce (10); 

    // here's a bunch of requests 
    std::vector<int> req (500); 

    for (size_t i=0;i<req.size();i++) { 
     scarce.tick(); 
     // once we get here, we know that we haven't ticked 
     // more than 10 times in the last second. 

     // do something interesting with req[i] 
    } 
} 

Answer 3

Algo bastante poderoso es el comando snippet.Digamos que tiene una función como esta:

/*!@brief Factory 
* 
* Creates sthg 
*/ 
sthg* Create(); 

y que le gustaría añadir una parte del archivo sthgTests/sthg_factory.cpp:

• Editar sthgTests/sthg_factory.cpp y añadir una etiqueta alrededor de la parte del código que le gustaría a aparecer en la documentación (dicen que el uso de una etiqueta llamada test_factory) así:

  //! [test_factory] 
  void test_factory() 
  { 
      // code here 
  } 
  //! [test_factory] 
  

• a continuación, utilice el comando como este fragmento :

  /*!@brief Factory 
  * 
  * Creates sthg 
  * @snippet sthgTests/sthg_factory.cpp test_factory 
  */ 
  sthg* Create(); 
  

Este enfoque es fácil de configurar y más barato de mantener.