Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

c++ Doxygen \example and description

Tags:

c++

doxygen

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.

like image 998
Beat Scherrer Avatar asked Aug 30 '18 14:08

Beat Scherrer


People also ask

What is doxygen in C?

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D.

What is the use of doxygen?

This medication is used to treat a wide variety of bacterial infections, including those that cause acne. This medication is also used to prevent malaria. This medication is known as a tetracycline antibiotic. It works by stopping the growth of bacteria.

How do I show code in doxygen?

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.

How do I comment out a code in doxygen C++?

Once specified, you can generate the comment stub by typing the respective “///” or “/**” above a function, or by using the (Ctrl+/) shortcut.


1 Answers

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.

like image 189
Nicol Bolas Avatar answered Sep 29 '22 23:09

Nicol Bolas