How can I include a subset of a .cpp file in a Doxygen comment?

Question

I'm trying to write some Doxygen comment blocks, and I'd like to include example snippets of code. Of course, I'd like the examples to actually compile so they don't get stale.

My example.cpp (that I \include in the .h file) looks like this:

#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

and my header file (that I'm running Doxygen) looks like this:

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

And I'd like to get doxygen to just include stuff starting at "void demo" to the end of the file (but without the // endcode).

I've tried experimenting with \dontinclude and \skip, \skipline, and \until, and I can't quite figure out the right incantations.

EDIT: included my .h file, and now I've almost got the right incantation. This does almost exactly what I want, is there some way to use \until without a tag, and get rid of that last // endcode line from example.cpp?

Answer 1

EDITED to add 2nd arg to clip macro.

Here's what I've done, which seems to work for me. Mostly taken from hint from EricM....

my source file Time_Limiter_example.cpp is:

#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

And I want to include it, but not have the #includes at the top.

I defined an ALIAS in my Doxyfile as:

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

And in my header, my comment looks like this:

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

And that does exactly what I want, including just the funciton tl_demo () from the .cpp file.

Answer 2

Something rather powerful is the snippet command. Say you have a function like this:

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

And you would like to add a part of the file sthgTests/sthg_factory.cpp:

• Edit sthgTests/sthg_factory.cpp and add a tag around the part of the code you would like to appear in the documentation (say using a tag named test_factory) like this:

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

• Then use the snippet command like this:

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

This approach is easy to setup and rather cheap to maintain.