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

Answer 3

I had some errors using @example to include the example file in the documentation. This is the workaround I used.

Place examplefile.cs in a folder/project specifically for example code. Place that folder in the Doxygen EXCLUDE list (Expert->Input->EXCLUDEin Doxygen GUI frontend) and in the EXAMPLE_PATH (Expert->Input->EXAMPLE_PATH in Doxygen GUI frontend)

Place this code block somewhere in a documented file (I put it in the file the example is for.)

/** @example examplefile.cs
 * A description of the example file, causes the example file to show up in 
 * Examples */

This causes the file to show up under Examples in the Doxygen menu, but not show up as a class/file in your project.

Then document your class/function:

/** @brief MyClass does something
 * @details I have something more long winded to say about it.  See example 
 * in examplefile.cs: @include examplefile.cs */

This causes the example file to print out in it's entirety in the documentation of MyClass.

Answer 4

1. add a way to doxyfile EXAMPLE_PATH = dir_example \

2. can connect all of the examples in the same file such example_list.h and include it in doxyfile INPUT = example_list.h \

(language - Russian) http://www.scale-tech.ru/SimBookmaker/doc/html/examples__list_8h_source.html and http://www.scale-tech.ru/SimBookmaker/doc/html/examples.html