How to integrate examples with Doxygen?

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?

score 47 · Accepted Answer · edited Dec 24 '18 at 16:53

47

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?

edited Dec 24 '18 at 16:53

albert

8,285
3
19
32

answered Jan 24 '12 at 10:23

Loebl

1,381
11
21

1

Yes I did that but the .cpp-files in the extra page are empty :/ – Tobi Weißhaar Jan 24 '12 at 10:44
hmmm does doxygen give any warning or error? – Loebl Jan 24 '12 at 10:48
No. I included the example files in the INPUT tag and in the tag EXAMPLE_PATH the files that have the tag \example...dont know whats the fault – Tobi Weißhaar Jan 24 '12 at 10:50
Do I have to use a special tag in the example cpp-files? – Tobi Weißhaar Jan 24 '12 at 10:53
you may need to swap it. I will give an example: You have all source code in `myproject/src`, examples (which are just commented source code) in `myproject/examples` and extra documentation files (which may use examples) in `myproject/doc`. In the config, INPUT will need `myproject/src` and `myproject/doc`. EXAMPLE_PATH should be set to `myproject/examples`. – Loebl Jan 24 '12 at 10:57
I got it...I forgot to add the example cpp-files to the EXAMPLE_PATH^^ – Tobi Weißhaar Jan 24 '12 at 11:00
I find it hard to follow their documentation. Too many words for a quick question/answer. I just opened SO and here we go! Thanks. – rightaway717 Jan 29 '15 at 07:11

score 23 · Answer 2 · answered Apr 16 '13 at 10:14

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

Using \snippet is just what I need. I've found that I get an empty box with no code whenever I include a \brief description on the element I want to attach a \snippet to. — Scott Langham, Sep 07 '15 at 10:16
A-ha! but using a \section to add a title allows me to include the \brief too. — Scott Langham, Sep 07 '15 at 10:17
In TestClass.cpp the comments must match the snippets, e.g. `// [TestClass Example]` — mrtnlrsn, Nov 08 '19 at 11:06

score 2 · Answer 3 · answered Mar 06 '13 at 19:29

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.

score 1 · Answer 4 · edited Apr 12 '13 at 13:02

1

add a way to doxyfile EXAMPLE_PATH = dir_example \
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

edited Apr 12 '13 at 13:02

Jens Erat

37,523
16
80
96

answered Apr 12 '13 at 12:44

Denis

69
1
1

How to integrate examples with Doxygen?

4 Answers4

Linked