c++ Doxygen \example and description

Question

I am using doxygen version 1.8.8 to build the C++ documentation. I included a detailed description of my templated class as follows:

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 */
template<>
class test
{
  //some class
};

and want to include an example to a file called testexample.cpp

if I just put the @example at the end of the detailed description the detailed description is applied to the example.

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 *  @example testexample.cpp
 *  An example of the test class.
 */
template<>
class test
{
  //some class
};

How can I have a detailed description of the class AND a link to a file of an example which shows the usage of the class in a detailed manner?

In the doxygen example of @example they reference an example to a member variable. And the example is linked to this member function. This is not what I wish to achieve in this case since I want to show how this class can be used in a fully working example and not only in a usage instruction.

Answer 1

The way Doxygen works with examples is that a code example is a separate page from regular documentation. So @example is like @page or @module : it takes the entire documentation block and applies it to the example's page. And any documented entity that gets used within that example code will have its documentation augmented with links to that example.

So what you need is a standalone documentation block like this:

/**
 *  @example testexample testexample.cpp
 *  An example of the test class.
 */

This doesn't have to be in the same file as your test class.

Answer 2

After having received the answer from nicol, I achieved what I was looking for in the following way:

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 */
template<>
class test
{
  //some class
};
/**@example TestExample.cpp
 * Simple example of how to use the test class
 */

I tried it this way already but because I did not set the EXAMPLE_PATH in the Doxyfile the example could not have been found and thus the @example tag became useless. After having specified the EXAMPLE_PATH everything worked as expected.