How do I give example code for a class with Doxygen?

Question

I'm trying to document a class embedded within a namespace, and I would like to give example usage. I have the examples written and included, and they show up in the examples tab. However, they are not referenced in the class itself. For instance, from the code on this page, their Doxygen command is written as:

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */

It seems that Doxygen parses the command and the file and recognizes that the Test class is referenced. That doesn't seem to be happening for me. This feature isn't very well documented, and is almost impossible to Google for.

This is the general layout of my code:

namespace exampleSpace
{
  ///Doxygen documentation

  class exampleClass {};

  ///@example example1.cpp
  ///  example1 description
  ///@example example2.cpp
  ///  example2 description
}

The example descriptions name the class, as does the one in the official documentation. However, Doxygen seems to recognize theirs and not mine.

My example code is complete and compiles/runs correctly.

So where is the correct place to put these commands so Doxygen knows that they are examples for this specific class?

EDIT: It seems Doxygen is actually parsing the source, as it successfully links to the class and any member functions within the code. However, the class page itself doesn't link to the files.

It may expect you to have the file and class descriptions as well. I can't remember in which context this helped me. — Mihai Todor
I'm not entirely sure what you mean. Are you saying the @example command expects a class description? From the documentation, it doesn't seem that way. I wouldn't even know how to specify it. — Littlegator
Did you set the EXAMPLE_PATH correctly in your Doxygen config file? — Anon Mail
Yes. The files are being displayed and parsed. In fact, it seems that explicitly declaring the namespace of the first class object made it work. — Littlegator

Horst Walter Horst Walter · Accepted Answer · 2016-03-04T18:10:02

I have used \snippet for that. You refer to another file, in that file you can surround a code block with [mytag] areas. Those are then displayed where \snippet is used.

See also https://stackoverflow.com/a/35759133/356726 and https://stackoverflow.com/a/16034375/356726

How do I give example code for a class with Doxygen?

2 Answers