How can I include a subset of a .cpp file in a Doxygen comment?
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?
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.
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.
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]
}
}