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

You can use the \cond tag, which conditionally includes things, so for example:

/// \cond HIDDEN_CODE

(the code here will not get documented)

/// \endcond

The HIDDEN_CODE label is just a placeholder; you can use whatever you want there. Doxygen will only document the code between \cond and \endcond tags if the condition label is in the ENABLED_SECTIONS part of your doxyfile.

Answer 2

I think \verbinclude should allow you to include a file as code and not have to put // \endcode at the last line.

EDIT: To clarify, I am suggesting that you put the code you want to include in its own include file, and use #include in the CPP file, and then use \verbinclude in the doxygen header file.

You source file would look like:

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

The file "Time_Limiter_example.inc" can then contain just the code example:

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

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.