如何指定 doxygen @examples 的順序

Question

Doxygen 有一個@example標簽，用於在生成的文檔末尾的補充部分中包含示例。

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

這似乎工作正常，但示例是按文件名排序的，最好在不修改文件名的情況下控制它們的順序。

如果您有 50 個示例並且在中間插入一個新示例將是一場悲劇，則尤其如此。

有一些選擇可以做到這一點嗎？

Answer 1

Doxygen 掃描所有文件以@example注釋塊並將它們合並以創建“特殊”示例頁面。 我想因為沒有一種簡單的方法來定義來自不同文件的@example塊的相對順序，所以 doxygen 只是簡單地按字典順序排列它們。

一種解決方法是自己構建一個包含已排序示例列表的專用頁面。 假設你有兩個例子

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

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

在你的源代碼中的某個地方。 然后你可以創建一個專用頁面

/**
@page SortedList Sorted list of examples

@ref example2.cpp

@ref example1.cpp
*/

以您希望的順序引用示例。

如果這些示例是建立在彼此之上的，也許使用@include命令創建一個內聯示例代碼的專用頁面也很有意義：

/**
@page CustomExamplePage Custom list of examples

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

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

這將提供一個類似教程的頁面，可能更容易閱讀。