How to integrate examples with Doxygen? [closed]

Question

I documented all of my classes and now I want to integrate an example of how to use these classes. How do I do that?

Answer 1

You can put example source code in a special path defined in the doxygen config under EXAMPLE_PATH, and then insert examples with the @example tag.

Doxygen will then generate an extra page containing the source of the example. It will also set a link to it from the class documentation containing the example tag.

Alternatively if you want to use small code snippets you can insert them with @code ... @endcode

The documentation for this is here: doxygen documentation?

Answer 2

Another way of doing it is to use the \snippet command.

• In your header file write something like:

\section ex1 Example \snippet path_to_test_class/TestClass.cpp TestClass example \section ex2 Expected output \snippet path_to_test_class/TestClass.cpp TestClass expected output 

• In the TestClass.cpp file, have something like:

 //! [OptimizeSpeedOnTrackTest example]  Class c;  const double res = c.do_something();  //! [OptimizeSpeedOnTrackTest example]  //! [OptimizeSpeedOnTrackTest expected output]  ASSERT_DOUBLE_EQ(5,res);  //! [OptimizeSpeedOnTrackTest expected output] 

path_to_test_class must be in your EXAMPLE_PATH.

This gives you the following:

• Your examples aren't just there for documentation: they provide test coverage as well
• Your test runner (& your compiler) give you the insurance that your examples actually compile & run
• It fits in pretty nicely in a TDD workflow