Comment puis-je inclure un sous-ensemble d'un fichier .cpp dans un commentaire Doxygen?

Question

J'essaie d'écrire des blocs de commentaires Doxygen, et j'aimerais inclure des exemples de code. Bien sûr, j'aimerais que les exemples compilent pour qu'ils ne soient pas viciés.

Mon example.cpp (que je \ Include dans le fichier .h) ressemble à ceci:

#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 

et mon fichier d'en-tête (que je suis en cours d'exécution Doxygen) ressemble à ceci:

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

Et j'aimerais que doxygen inclue juste des choses commençant à "void demo" jusqu'à la fin du fichier (mais sans le // endcode).

J'ai essayé d'expérimenter \ neinclude et \ skip, \ skipline, et \ until, et je n'arrive pas à trouver les bonnes incantations.

EDIT: inclus mon fichier .h, et maintenant j'ai presque la bonne incantation. Cela fait presque exactement ce que je veux, est-il un moyen d'utiliser \ jusqu'à ce que sans une balise, et se débarrasser de cette dernière // endcode ligne de example.cpp?

Answer 1

ÉDITÉ ajouter 2 arg à clipser macro.

Voici ce que j'ai fait, qui semble fonctionner pour moi. La plupart du temps pris de soupçon de EricM ....

mon fichier source est 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 

Et je veux inclure, mais pas les #includes en haut.

Je définis un ALIAS dans mon Doxyfile comme:

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

Et dans mon tête, mon commentaire ressemble à ceci:

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

Et qui fait exactement ce que je veux, y compris tout le funciton tl_demo() du fichier .cpp.

Answer 2

Je pense que \verbinclude devrait vous permettre d'inclure un fichier comme code et ne pas avoir à mettre // \endcode à la dernière ligne. EDIT: Pour clarifier, je suggère que vous mettez le code que vous voulez inclure dans son propre fichier include, et utilisez #include dans le fichier CPP, puis utilisez \verbinclude dans le fichier d'en-tête doxygen.

fichier source ressemblerait à ceci:

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

Le fichier "Time_Limiter_example.inc" peut alors contenir juste l'exemple de code:

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

Quelque chose d'assez puissant est la commande snippet.Disons que vous avez une fonction comme ceci:

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

Et vous voulez ajouter une partie du fichier sthgTests/sthg_factory.cpp:

• Modifier sthgTests/sthg_factory.cpp et ajouter une balise autour de la partie du code que vous souhaitez apparaître dans la documentation (par exemple en utilisant une balise nommée test_factory) comme ceci:

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

• Ensuite, utilisez la commande d'extrait comme celui-ci :

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

Cette approche est facile à installer et à maintenir, plutôt pas cher.