How to specify ordering for doxygen @examples-CodePudding

Doxygen has a @example tag to in include examples in a supplemental section at the end of the generated document.

/**
 *  Some example
 *  @example my_example.cpp
 */

This seems to work fine but the examples are sorted by filename and it would be preferable to control their order without modifying the filenames.

This is especially true if you have like 50 examples and inserting a new one in the middle would be a tragedy.

Is there some option that does this?

CodePudding user response：

Doxygen scans all files for @example comment blocks and merges them to create the "special" examples page. I guess since there isn't an easy way to define the relative order of @example blocks from different files, doxygen simply orders them lexicographical.

One workaround would be to build a dedicated page with the sorted list of examples yourselves. Assume you have the two examples

/**
@example example1.cpp
Desc 1
*/

/**
@example example2.cpp
Desc 2
*/

somewhere in your source code. Then you could created a dedicated page

/**
@page SortedList Sorted list of examples

@ref example2.cpp

@ref example1.cpp
*/

that references the examples in the order you wish.

If the examples are building on top of each other, maybe it also makes sense to create a dedicated page with the example code inlined, using the @include command:

/**
@page CustomExamplePage Custom list of examples

Example 2:
@include example2.cpp
More text 2.

Example 1:
@include example1.cpp
More text 1.
*/

This would give a tutorial-like page that might be easier to read.