"New API In version A.B.C" doxygen 中的页面

Question

有一个 Doxygen 选项可以指定 API 何时使用 \since 标签出现，例如

///
/// Does foo
///
/// \since 1.5
///
void foo();

它会出现在 foo() 的文档中。

我正在寻找一种自动创建包含所有 API 页面的方法出现在 1.5 - 即列出所有 \since 1.5 或可能标记的 API 一些其他标签（如果可用）。

编辑： 我尝试使用 \ingroup 并创建一个包含所有新 API 的组页面，并且它有效。但是它将描述移动到此页面，例如将新方法从 class 定义移动到页面 "New in 1.2.3"，这不是我想要的。

Answer 1

您想为当前 item 创建一个 external reference，一个 \xrefitem:

\xrefitem version_change_1_0_0 "Since 1.0.0" "Changes in 1.0.0" ...
             <key>               <heading>    <list title>      <text>

共享相同 <key> 的所有项目都将显示在一个特殊生成的页面上。 <heading> 将用于在您使用 \xrefitem 的地方开始一个部分，而 <list title> 将用作标题结果页面（见下面的备注）。文字可以随意。

你得到的结果类似于\todo和\bug的列表和外观，你甚至可以认为\bug和\todo实现为

\bug  <text> = \xrefitem bug  "Bug"  "List of bugs" <text>
\todo <text> = \xrefitem todo "Todo" "List of todos" <text>

不幸的是，关键 cannot contain dots:

ID        "$"?[a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF]*
LABELID   [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*

因此，您必须使用带有（至少）两个参数的别名，一个用于标签，一个用于实际文本：

ALIASES += sinceversion{3}="\xrefitem version_changes \"Since \" \"Changes in \" \n\n"
ALIASES += sinceversion{2}="\sinceversion{,,Introduced in this version.}"

如果你从不使用点，你当然可以进一步简化别名。这将为您提供两个新命令：

\sinceversion{label, version}
\sinceversion{label, version, custom text}

在这两种情况下，标签只能包含字母数字符号，版本可以是任意的。如果您不提供自定义文本，将显示 "Introduced in this version"。

如果有标识符为 version_changes<label> 的页面，将添加更改列表。请注意 \page 的标题将覆盖 \xrefitem 给出的标题，这对于主要版本来说很方便。

例子

这是 \sinceversion 的用法示例。请注意，如果您记录了版本 x.y.z:

的大量更改，您可能想使用另一个别名，例如 ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,X.Y.Z,}"

示例代码

/** Foos around.
 * \sinceversion{001,0.0.1}
*/
void foo(){}

/** Bars around.
 * \sinceversion{001,0.0.1}
 * \sinceversion{002,0.0.2,Removed a memory leak}
*/
void bar(){}

/** \page version_changes002 Changes in 0.0.2
  *
  * We found several memory leaks and removed them
 */

"New API In version A.B.C" doxygen 中的页面

"New API In version A.B.C" page in doxygen

versioning

doxygen

例子

示例代码

版本变更页面列表

每个版本的更改列表

每个版本的更改列表及附加说明

功能文档更改的外观