How to include sub-assembly of a .cpp file in a Doxygen comment?

Question

I am trying to write some Doxygen comment blocks, and I would like to include sample code snippets. Of course, I would like the examples to really compile so that they are not out of date.

My .cpp example (which is 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 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 (which I am running Doxygen) is as follows:

 /** * \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 would like doxygen to just include stuff starting from "void demo" to the end of the file (but without // endcode).

I tried experimenting with \ dontinclude and \ skip, \ skipline and \ until, and I cannot figure out the correct spells.

EDIT: included my .h file, and now I almost got the correct spell. This is almost what I want, is there a way to use \ up without a tag and get rid of this last line of endcode from example.cpp?

Answer 1

EDITED add the second argument to the clip macro.

Here is what I did, which seems to work for me. Mostly from a hint from EricM ....

my source file is 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 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 does not have #includes at the top.

I defined ALIAS in my Doxyfile as:

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

And in my headline, 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 only the funciton tl_demo () from the .cpp file.

Answer 2

Something quite powerful is the snippet team. Say you have a function like this:

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

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

• Edit sthgTests/sthg_factory.cpp and add a tag around the part of the code that you want to display in the documentation (say, using a tag called test_factory ), for example:

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

• Then use the snippet command as follows:

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

This approach is easy to set up and fairly cheap to maintain.

Answer 3

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

EDIT: To clarify, I suggest you add the code you want to include in your own include file and use #include in the CPP file and then use \verbinclude in the doxygen header file.

The source file will look like this:

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

The file "Time_Limiter_example.inc" can contain only sample 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 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] } }