CODEWITHSUNDEEP
c++classdoxygen
Littlegator
Littlegator

Reputation: 395

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

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.

Upvotes: 2

Views: 4316

Answers (2)

Horst Walter
Horst Walter

Reputation: 14081

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

Upvotes: 2

Geoff Reedy
Geoff Reedy

Reputation: 36071

Just a guess at this point, but I bet Doxygen is not matching things up because of the namespace.

Some ideas to make the linking happen:

  • Explicitly qualify the namespace of all names in the examples
  • Put the code in the examples in the namespace

Upvotes: 1

Related Questions