doxygen 中的“A.B.C 版中的新 API”页面

Question

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

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

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

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

编辑：我尝试使用\ingroup 并在那里创建一个包含所有新API 的组页面，并且它可以工作。但它会将描述移动到此页面，例如将新方法从类定义移动到“1.2.3 中的新方法”页面，这不是我想要的。

Answer 1

你想为当前item创建一个电子x外部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\1 \"Since \2\" \"Changes in \2\" \3\n\n"
ALIASES += sinceversion{2}="\sinceversion{\1,\2,Introduced in this version.}"

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

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

在这两种情况下，标签只能包含字母数字符号，版本可以是任意的。如果您不提供自定义文本，则会显示“在此版本中引入”。

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

示例

这是\sinceversion 的用法示例。请注意，如果您记录了 x.y.z 版本的大量更改，您可能希望使用另一个别名，例如 ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,X.Y.Z,\1}"：

示例代码

/** 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
 */

版本变更页面列表

每个版本的更改列表

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

功能文档变化的外观