状态

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

\abstract 以及\qmlabstract

\abstract是\qmlabstract 命令的同义词。当某个QML类型仅作为抽象基类使用时，请在该类型的 \qmltype QML 类型的注释中，当该类型仅作为抽象基类使用时。当一个 QML 类型为抽象类型时，意味着该 QML 类型无法被实例化。 相反，其公共 API 中的属性会被纳入每个继承该抽象 QML 类型的 QML 类型的参考页面中的公共属性列表中。这些属性在文档中的描述，就如同它们是继承该 QML 类型的属性的那样。

通常，当一个 QML 类型被标记为 \qmlabstract，它也会被标记为 \internal ，从而不会生成其参考页面。如果该抽象 QML 类型未被标记为内部类型，则文档中会为其生成参考页面。

\attribution

\attribution 命令会为已记录的 \page 标记为许可归属文档。

\generatelist annotatedattributions命令会生成一份带注释的列表，其中包含文档项目中所有许可归属页面。

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

请参阅State 类型的参考页面，了解 QDoc 如何呈现该属性。

\qmlenumeratorsfrom

\qmlenumeratorsfrom 在包含属性类型枚举的 \qmlproperty 包含属性类型枚举的主题中，可自动复制 C++ \enum 主题中自动复制枚举器的文档。

该命令以一个完全限定的 C++ 枚举作为参数，并生成一个枚举项及其描述的列表。

默认情况下，每个枚举项名前缀为该属性所属的类型名称，并以. 作为分隔符。

例如：

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

如果枚举器是在 QML 中以不同的类型名称注册的，则可以使用方括号中的可选参数指定该名称（前缀）：

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

该命令于 QDoc 6.8 版本中引入。

另请参阅 \qmlproperty， \enum，以及 \value。

\dontdocument

\dontdocument 命令仅用于特定模块的dontdocument.qdoc文件中。该文件指定了不应被文档化的公开声明的类或结构体。对于这些类和结构体，QDoc不会因缺少\class 注释而显示警告。

下面是小部件（widgets）的 dontdocument.qdoc 文件中包含的\dontdocument 命令：

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

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

默认情况下，QDoc 会将 `\class SomeClass ` 记录为可通过以下 `include` 语句使用：

#include <SomeClass>

如果实际的 include 语句与默认值不同，则可将其记录为

\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;
}

除非在调用 QDoc 时指定了-showinternal 命令行选项，或者设置了QDOC_SHOW_INTERNAL 环境变量，否则该函数不会被包含在文档中。

\modulestate

请在\module 或\qmlmodule 主题中使用\modulestate 命令，以提供自定义模块状态描述。

该命令接受一个描述模块状态的参数。例如：

/*!
    \module QtFoo
    \modulestate Experimental
*/

随后，QDoc 将在模块页面上添加此信息：

该模块处于“实验性”状态。

在HTML输出中，此状态信息也会显示在该模块成员所属页面导航栏（面包屑导航）中。

另请参阅 \preliminary。

\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);
}

自 QDoc 6.12 版本起，可以自定义标记为\preliminary 的元素的状态描述符以及生成的注释内容。

另请参阅 preliminary 配置变量。

\readonly

\readonly 命令需与 \qmlproperty 命令配合使用，用于将 QML 属性标记为只读。

\required

\required 命令需与 \qmlproperty 命令配合使用，用于将 QML 属性标记为必填项。

另请参阅 《属性系统》。

\since

\since 命令用于说明相关功能是在哪个次版本中添加的。

如果传递给 `\since ` 的参数中不包含空格，则将其视为 `productname` 的简写形式，QDoc 会在生成的输出中为版本号添加 `productname ` 的值作为前缀。如果 `productname ` 未定义，QDoc 仅生成版本字符串。

该参数也可以显式包含产品名称：

\since MyFramework 2.0

在这种情况下，参数（product 和 version）将按原样使用。

“自”信息的继承

自 QDoc 6.5 版本起，C++ 类和 QML 类型会从其各自的模块或 QML 模块继承 `\since ` 语句，除非在类型文档中显式使用了 `\since `。

Since子句

\value 命令允许在命令字符串之后紧跟一个用方括号括起的可选since子句。这用于为特定的C++枚举值标注since信息。

另请参阅 \value 以及ignoresince。

\wrapper

在 C++ 类文档中使用 `\wrapper ` 命令时，会将该类标记为提供对非 Qt API 访问权限的封装类。该命令用于抑制此类类的成员可能引发的警告。