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

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

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

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

Deprecated Members for MyClass

The following class members are deprecated. We strongly advise against using them in new code.

...

void MyDeprecatedFunction() (deprecated)

...

Member Function Documentation

void MyDeprecatedFunction ()

This function is deprecated since 6.2. It is provided to keep old source code working. We strongly advise against using it in new code. 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.

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

QDoc renders this as:

JoiningType QChar::joiningType() const

This function is under development and subject to change.

Returns information about the joining type attributes of the character (needed for certain languages such as Arabic or Syriac).

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

...

JoiningType joiningType() const (preliminary)

...

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

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

QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const

This function was introduced in Qt version 4.1.

Returns an icon for standardIcon.

...

See also standardPixmap().

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