状态

这些命令用于指示文档元素的某些特殊状态。该元素可能被标记为过时元素，也就是说，它即将被淘汰，不再包含在公共界面中。该 \since命令用于指定函数或类首次出现的版本号。该 \qmlabstract命令用于将 QML 类型标记为抽象基类。

\abstract 和\qmlabstract

\abstract是\qmlabstract 命令的同义词。当 QML 类型只用作抽象基类时 \qmltype注释中。当 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 表示只比较类型是否相等。

QDoc 在 Qt 6.7 中引入了此命令。

另请参见 \compareswith.

\compareswith

\compareswith .. \endcompareswith \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 表示只比较类型是否相等。

QDoc 在 Qt 6.7 中引入了此命令。

另请参见 \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);
}

\readonly

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

\required

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

另请参阅"属性系统"。

\since

\since 命令会显示相关功能是在哪个次版本中添加的。

如果传给\since 的参数不包含空格，则假定它是产品名称的速记符号，QDoc 将在生成的输出中以productname 的值作为版本的前缀。如果productname 变量未定义，QDoc 将只生成版本字符串。

参数也可以明确包含产品名称：

\since MyFramework 2.0

在这种情况下，参数（产品和版本）按原样使用。

自信息的继承

自 QDoc 6.5 版起，C++ 类和QML 类型从各自的模块或QML 模块继承\since 语句，除非在类型文档中明确使用\since 。

自语句

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

另请参见 \value和ignoresince。

\wrapper

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