状态

这些命令用于指示文档化的元素具有某些特殊状态。该元素可能被标记为 已弃用，即它将被废弃，不再包含在公共接口中。\since 命令用于指定函数或类首次出现的版本号。\qmlabstract 命令用于将 QML 类型标记为抽象基类。

\abstract 和 \qmlabstract

\abstract 是 \qmlabstract 命令的同义词。当一个 QML 类型打算只用作抽象基类时，将它添加到 \qmltype 注释中。当 QML 类型是抽象的，这意味着这个 QML 类型不能实例化。取而代之的是，它的公共 API 中的属性包含在每个继承自抽象 QML 类型的 QML 类型参考页的公共属性列表中。属性按照继承自 QML 类型的方式被记录。

通常，当 QML 类型用 \qmlabstract 标记时，它也被标记为 \internal，以便不生成其参考页面。如果抽象 QML 类型没有标记为内部类型的，它将在文档中有一个参考页面。

\default

\default 命令用于记录 QML 属性的默认值。该命令接受一个参数，该参数在文档中显示为默认值。

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

如果默认值是非空字符串，请使用引号

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

使用 \compares 命令描述记录的 C++ 类型在与其自身比较的结果。必须与 \class 命令结合使用。

\compares 接受以下参数之一

strong
partial
weak
equality

strong、partial 和 weak 与排序有关。equality 表示只比较类型是否相等。

此命令自 Qt 6.7 起被引入到 QDoc 中。

另请参阅 \compareswith。

\compareswith

使用\compareswith .. \endcompareswith命令对一起描述，说明已记录的C++类型与其他类型的比较结果。\compareswith需要两个或更多参数：一个比较类别，后跟一个类型名，或者多个类型名（空格分隔）。任何出现在\compareswith和\endcompareswith之间文本行的内容均被视为适用于所有受比较类别参数影响的类型的详细信息。

类型名称中包含一个或多个空格的类型，例如unsigned long，应该用花括号括起来。

例如

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

用花括号括起来的参数会去除前导和尾随空格。例如，unsigned long和unsigned long是等价的。

比较类别参数必须是以下之一

strong
partial
weak
equality

strong、partial 和 weak 与排序有关。equality 表示只比较类型是否相等。

此命令自 Qt 6.7 起被引入到 QDoc 中。

另请参阅\compares命令。

\qmldefault

\qmldefault命令用于将QML属性标记为默认属性。文档中会显示单词default。

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

请看QDoc在State类型的参考页面是如何呈现此属性的。

\dontdocument

\dontdocument命令仅在特定模块的dontdocument.qdoc文件中使用。该文件指定了不应进行文档化的公开声明的类或结构体。QDoc不会为这些类和结构体打印缺失的\class注释的警告。

下面是widgets的dontdocument.qdoc中的\dontdocument命令

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

\inheaderfile元命令用于覆盖为C++类、命名空间或头文件参考文档生成的包含语句。

默认情况下，QDoc将一个\class SomeClass文档说明为可用，下面的包含语句

#include <SomeClass>

如果实际的包含语句与默认值不同，可以按如下方式文档说明

\class SomeClass
\inheaderfile Tools/SomeClass
...

另请参阅\class和\headerfile命令。

\obsolete

命令\obsolete已被\deprecated命令取代。

仅出于向下兼容的原因保留此命令。它可能在QDoc的未来版本中删除。请改用\deprecated命令。

另请参阅\deprecated命令。

\deprecated

\deprecated命令用于指示某个函数正在被弃用，并且不应该在新代码中使用。它不会保证该功能在库中保留多久。

\deprecated命令有两个可选参数

方括号中的版本号（例如：[6.2]）。
包含更多信息的字符串，例如建议的替换项。

当生成类的参考文档时，QDoc将创建并将其链接到单独的页面来记录其已弃用的函数。建议提供一个等效函数作为替代是良好的做法。

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\internal

\internal命令指示引用的函数不是公共接口的一部分。

命令必须单独位于一行上。

当生成相关类参考文档时，QDoc将忽略文档以及文档化的项目。

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

此功能不会包含在文档中，除非使用带有 -showinternal 命令行选项或设置 QDOC_SHOW_INTERNAL 环境变量的 QDoc 调用。

\modulestate

可以在 \module 或 \qmlmodule 主题中使用 \modulestate 命令提供模块状态描述，除了初步或 已弃用。

行余下的部分视为描述模块状态的参数。例如

/*!
    \module QtFoo
    \modulestate Technical Preview
*/

QDoc 将在此模块页面添加此信息

此模块处于 技术预览 状态。

在 HTML 输出中，此状态信息也出现在模块成员的参考页面导航栏（面包屑）中。

\preliminary

\preliminary 命令用于指示所引用的函数仍在开发中。

命令必须单独位于一行上。

\preliminary 命令扩展为函数文档中的通知，并在列表中出现时将函数标记为“初步”。

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

\readonly

\readonly 命令与 \qmlproperty 命令一起使用，以标记 QML 属性为只读。

\required

\required 命令与 \qmlproperty 命令一起使用，以标记 QML 属性为必需。

另请参阅 属性系统.

\since

\since 命令告知相关功能是在哪个次要版本中添加的。

如果传递给 \since 的参数不包含空格，则假定它是 Qt 项目的版本号字符串，且 QDoc 将在生成的输出中加上 'Qt' 前缀。该参数还可以显式包含项目名称。

\since MyFramework 2.0

在这种情况下，参数（项目版本）将被直接使用。

Since 信息继承

自从 QDoc 版本 6.5 以来，C++ 类和 QML 类型从其各自的模块或 QML 模块继承 \since 声明，除非在类型文档中显式使用 \since。

Since 子句

\value 命令允许在命令字符串后立即跟随可选的 since 子句，括在方括号内。这用于标记具有 since 信息的特定 C++ 枚举值。

另请参阅 \value 和 ignoresince.

\wrapper

\wrapper 命令在 C++ 类文档中用作 包装器 标记，该包装器提供对非 Qt API 的访问。此命令用于抑制可能会为此类成员生成的警告。

文档导航线程支持