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 extraits de code à titre d'exemple. Bien entendu, j'aimerais que les exemples soient effectivement compilés afin qu'ils ne deviennent pas obsolètes.

Mon fichier example.cpp (que j'ai \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 j'exécute avec 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 n'inclue que les éléments commençant par "void demo" jusqu'à la fin du fichier (mais sans le code de fin //).

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

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

Answer 1

Quelque chose d'assez puissant est le snippet commandement. Disons que vous avez une fonction comme celle-ci :

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

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

• Editar sthgTests/sthg_factory.cpp et ajoutez une balise autour de la partie du code que vous souhaitez voir 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 snippet comme ceci :

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

Cette approche est facile à mettre en place et plutôt bon marché à maintenir.

Answer 2

MODIFIÉ pour ajouter la deuxième arg à la macro de clip.

Voici ce que j'ai fait, qui semble fonctionner pour moi. Principalement tiré de l'astuce d'EricM....

mon fichier source Time_Limiter_example.cpp est :

#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 l'inclure, mais sans avoir le #includes en haut.

J'ai défini un ALIAS dans mon Doxyfile comme :

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

Et dans mon en-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 cela fait exactement ce que je veux, y compris juste la fonction tl_demo () du fichier .cpp.

Answer 3

Je pense \verbinclude devrait vous permettre d'inclure un fichier en tant que code et de ne pas avoir à mettre // \endcode à la dernière ligne.

EDIT : Pour clarifier, je suggère que vous mettiez le code que vous voulez inclure dans son propre fichier include, et utilisez #include dans le fichier CPP, et ensuite utiliser \verbinclude dans le fichier d'en-tête doxygen.

Votre 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 uniquement 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]
    }
}