How to integrate examples with Doxygen? [closed] - documentation

Question

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this 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

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