Status

These commands are for indicating that a documented element has some special status. The element could be marked deprecated, that is, it's about to be made obsolete and no longer included in the public interface. The \since command is for specifying the version number in which a function or class first appeared. The \qmlabstract command is for marking a QML type as an abstract base class.

\abstract and \qmlabstract

\abstract is a synonym for the \qmlabstract command. Add this command to the \qmltype comment for a QML type when that type is meant to be used only as an abstract base type. When a QML type is abstract, it means that the QML type that can't be instantiated. Instead, the properties in its public API are included in the public properties list on the reference page for each QML type that inherits the abstract QML type. The properties are documented as if they are properties of the inheriting QML type.

Normally, when a QML type is marked with \qmlabstract, it is also marked with \internal so that its reference page is not generated. It the abstract QML type is not marked internal, it will have a reference page in the documentation.

\default

The \default command is used for documenting a default value for a QML property. The command takes a single argument, which is displayed in the documentation as the default value.

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

If the default value is a non-empty string, use quotes:

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

\compares

Use the \compares command to describe the comparison results for the documented C++ type when compared to itself. You must use this command in conjunction with the \class command.

\compares takes one of the following arguments:

• strong
• partial
• weak
• equality

strong, partial, and weak relate to the ordering. equality means that the type is only compared for equality.

This command was introduced to QDoc with Qt 6.7.

See also \compareswith.

\compareswith

Use the \compareswith .. \endcompareswith pair of commands to describe the comparison results for the documented C++ type when compared to other types. \compareswith takes two or more arguments: a comparison category, followed by a type name, or a space-separated list of type names. Any text lines between \compareswith and \endcompareswith commands are considered further details that apply to all types subject to the comparison category argument.

Types that have one or more space in their name, such as unsigned long, should be enclosed in braces.

For example:

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

Argument enclosed in braces have their leading and trailing whitespaces removed. For example, unsigned long and unsigned long are equivalent.

The comparison category argument must be one of the following:

• strong
• partial
• weak
• equality

strong, partial, and weak relate to the ordering. equality means that the type is only compared for equality.

This command was introduced to QDoc with Qt 6.7.

See also \compares.

\qmldefault

The \qmldefault command is for marking a QML property as the default property. The word default is displayed in the documentation of the property.

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

See how QDoc renders this property on the reference page for the State type.

\dontdocument

The \dontdocument command is only used in a dontdocument.qdoc file for a particular module. This file specifies publically declared classes or structs that are not meant to be documented. QDoc will not print warnings about missing \class comments for these classes and structs.

Below you will find the \dontdocument command in the dontdocument.qdoc for widgets:

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

The \inheaderfile meta-command is used for overriding the include statement generated for a C++ class, namespace, or header file reference documentation.

By default, QDoc documents a \class SomeClass to be available with a following include statement:

#include <SomeClass>

If the actual include statement differs from the default, this can be documented as

\class SomeClass
\inheaderfile Tools/SomeClass
...

See also \class and \headerfile.

\obsolete

The \obsolete command is superceded by the \deprecated command.

This command is kept for backwards compatibility reasons only. It may be removed in a future version of QDoc. Use the \deprecated command instead.

See also \deprecated.

\deprecated

The \deprecated command is for indicating that a function is being deprecated, and that it should no longer be used in new code. There is no guarantee for how long it will remain in the library.

The \deprecated command takes two optional arguments:

• A version in square brackets (e.g. [6.2]).
• A string with more information, for example a suggested replacement.

When generating the reference documentation for a class, QDoc will create and link to a separate page documenting its deprecated functions. It is good practice to suggest an equivalent function as an alternative.

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

\internal

The \internal command indicates that the referenced function is not part of the public interface.

The command must stand on its own line.

QDoc ignores the documentation as well as the documented item, when generating the associated class reference documentation.

/*!
    \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;
}

This function will not be included in the documentation, unless QDoc is called with the -showinternal command line option or the QDOC_SHOW_INTERNAL environment variable is set.

\modulestate

The \modulestate command can be used within a \module or \qmlmodule topic to provide a module state description other than preliminary or deprecated.

Rest of the line is taken as an argument that describes the module's state. For example:

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

QDoc will then add this information on the module page:

This module is in Technical Preview state.

In HTML output, this state information appears also in the navigation bar (breadcrumbs) of reference pages for the module's members.

\preliminary

The \preliminary command is for indicating that a referenced function is still under development.

The command must stand on its own line.

The \preliminary command expands to a notification in the function documentation, and marks the function as preliminary when it appears in lists.

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

The \readonly command is used in conjunction with a \qmlproperty command to mark the QML property as read-only.

\required

The \required command is used in conjunction with a \qmlproperty command to mark the QML property as required.

See also The Property System.

\since

The \since command tells in which minor release the associated functionality was added.

If the argument passed to \since contains no spaces, it is assumed to be a version number string for the Qt project, and QDoc will prefix it with 'Qt' in the generated output. The argument can also contain the project name explicitly:

\since MyFramework 2.0

In this case, the arguments (project and version) are used as is.

Inheritance of Since Information

Since QDoc version 6.5, C++ classes and QML types inherit the \since statement from their respective module or QML module, unless \since is explicitly used in the type documentation.

Since Clause

The \value command allows an optional since clause, enclosed in square brackets, to immediately follow the command string. This is used for marking specific C++ enum values with since information.

See also \value and ignoresince.

\wrapper

The \wrapper command, when used in a C++ class documentation, marks the class as a wrapper that provides access to a non-Qt API. This command is used for suppressing warnings that might otherwise be generated for members of such a class.