Come posso includere un sottoinsieme di un file .cpp in un commento Doxygen?

Question

Sto provando a scrivere alcuni blocchi di commenti Doxygen e vorrei includere frammenti di codice di esempio. Certo, mi piacerebbe che gli esempi venissero compilati in modo che non diventassero stantii.

mio example.cpp (che ho \ include nel file h) si presenta così:

#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 

e il mio file di intestazione (che sto correndo Doxygen) si presenta così:

/** 
* \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 
* 
**/ 

E mi piacerebbe ottenere doxygen per includere solo cose che iniziano da "void demo" alla fine del file (ma senza il // codice finale).

Ho provato a sperimentare con \ dontinclude e \ skip, \ skipline e \ until, e non riesco a capire i giusti incantesimi.

MODIFICA: incluso il mio file .h, e ora ho quasi il giusto incantesimo. Questo è quasi esattamente quello che voglio, c'è un modo per usare \ fino a quando non c'è un tag, e sbarazzarsi di quest'ultima riga // endcode da example.cpp?

Answer 1

A cura di aggiungere 2 ° arg a clip macro.

Ecco cosa ho fatto, che sembra funzionare per me. Per lo più tratto da suggerimento da EricM ....

mio file sorgente Time_Limiter_example.cpp è:

#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 

e voglio includere, ma non hanno le #include nella parte superiore.

ho definito un alias nel mio Doxyfile come:

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

E nella mia testa, il mio commento è simile al seguente:

/** 
* \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} 
**/ 

E che fa esattamente quello che voglio, tra cui proprio il funciton tl_demo() dal file .cpp.

Answer 2

Penso che \verbinclude dovrebbe consentire di includere un file come codice e non dover inserire // \endcode nell'ultima riga.

EDIT: Per chiarire, io sto suggerendo che si inserisce il codice che si desidera includere nel proprio file di inclusione, e utilizzare #include nel file CPP, e quindi utilizzare \verbinclude nel file di intestazione doxygen.

file sorgente si sarebbe simile:

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

Il file "Time_Limiter_example.inc" può allora contenere solo il codice di esempio:

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

Qualcosa di piuttosto potente è il comando snippet.Diciamo che avete una funzione come questa:

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

E si desidera aggiungere una parte del file sthgTests/sthg_factory.cpp:

• Modifica sthgTests/sthg_factory.cpp e aggiungere un tag attorno alla parte del codice che si desidera ad apparire nella documentazione (dicono utilizzando un nome di nome test_factory) come questo:

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

• quindi utilizzare il comando frammento di come questo :

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

Questo approccio è facile da installare e piuttosto economico da mantenere.