状态

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

\abstract和qmlabstract

\abstract 是 \qmlabstract 命令的同义词。当 QML 类型只用作抽象基类时，把这条命令添加到 QML 类型的\qmltype注释中。当一个 QML 类型是抽象的，它意味着该 QML 类型不能被实例化。相反，其公共 API 中的属性会包含在继承抽象 QML 类型的每个 QML 类型的参考页面上的公共属性列表中。这些属性被记录为继承 QML 类型的属性。

通常，当一个 QML 类型被标记为\qmlabstract 时，它也被标记为\internal这样它的引用页就不会生成。如果抽象 QML 类型没有标记为内部，它就会在文档中有一个引用页。

\（属性

属性（attribution）命令会将文档中的 \page标记为许可证归属文档。

generatelist annotatedattributions命令会生成文档项目中所有许可证属性页面的注释列表。

\默认

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

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

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

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

\比较

使用\compares 命令描述文档中的 C++ 类型与自身的比较结果。该命令必须与\class命令结合使用。

\compares 需要以下参数之一：

• strong
• partial
• weak
• equality

strong partial weak equality 表示只比较类型是否相等。

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

另请参见 \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 如何渲染该属性。

\来自

在具有枚举属性类型的 \qmlproperty属性类型枚举的主题中使用\qmlenumeratorsfrom 命令，可自动复制 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.qdoc 文件中使用。该文件指定了公开声明的类或结构体，这些类或结构体并不打算被文档化。QDoc 不会为这些类和结构体打印缺少 \class 注释的警告。

下面，你将在小部件的 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命令已被（deprecated）命令取代。

保留该命令只是为了向后兼容。它可能会在 QDoc 的未来版本中被删除。请使用 \deprecated 命令。

另请参见\deprecated.

\deprecated

\deprecated 命令用于指示函数已被弃用，新代码中不应再使用该函数。我们无法保证该函数会在库中保留多久。

\deprecated 命令有两个可选参数：

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

在生成一个类的参考文档时，QDoc 会创建并链接到一个单独的页面，记录其已废弃的函数。好的做法是提出一个等效的函数作为替代。

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

\内部

\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 主题中使用，以提供除preliminary或deprecated 之外的模块状态描述。

命令行的其余部分将作为描述模块状态的参数。例如

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

QDoc 将在模块页面上添加这些信息：

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

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

\初步

\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 命令与\qmlproperty命令结合使用，将 QML 属性标记为只读。

\required

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

另请参阅 属性系统。

\自

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

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

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

\since MyFramework 2.0

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

自信息的继承

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

Since 条款

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

另请参阅\value和ignoresince。

\wrapper

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