Status

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

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"
*/

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.

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)
* /

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.

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.

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

QDoc renders this in myclass-obsolete.html as:

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.

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

QDoc renders this as:

And the function's entry in QChar's list of public functions will be rendered as:

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

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

See also The Property System.

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

/ *!
    \since 4.1

    Returns an icon for \a standardIcon.

    ...

    \sa standardPixmap()
* /
QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
{
}

QDoc renders this as:

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.

Since Clause▲

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.