Status | QDoc Manual 5.8

Qt 5.8 | QDoc Manual | Status

Qt 5.8.0 Reference Documentation

Document Navigation ◦ Thread Support

# Status

These commands are for indicating that a documented element has some special status. The element could be marked as about to be made obsolete, or that it is provided for compatibility with an earlier version, or is simply not to be 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.

## \compat

The \compat command is for indicating that a class or function is part of the support library provided to keep old source code working.

The command must stand on its own line.

Usually an equivalent function or class is provided as an alternative.

If the command is used in the documentation of a class, the command expands to a warning that the referenced class is part of the support library. The warning is located at the top of the documentation page.

      \beginqdoc
          \class MyQt3SupportClass
          \compat
      \endqdoc

QDoc renders this at the top of the MyQt3SupportClass class reference page.

> This class is part of the Qt 3 support library. It is provided to keep old source code working. We strongly advise against using it in new code. See the Porting Guide for more information.

If the command is used when documenting a function, QDoc will create and link to a separate page documenting Qt 3 support members when generating the reference documentation for the associated class.

      \beginqdoc
          \fn MyClass::MyQt3SupportMemberFunction
          \compat

          Use MyNewFunction() instead.
      \endqdoc

QDoc renders this in `myclass-qt3.html` as:

> # Qt 3 Support Members for MyClass

> The following class members are part of the Qt 3 support layer. They are provided to help you port old code to Qt 4. We advise against using them in new code.

> ...

> - void MyQt3SupportMemberFunction()
> - ...

> ## Member Function Documentation

> ### void MyQt3SupportMemberFunction ()

> Use MyNewFunction() instead.

> ...

## \default

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

      / *!
          \qmlproperty list<Change> State::changes
          This property holds the changes to apply for this state.
          \default

          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.

## \obsolete

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

The command must stand on its own line.

When generating the reference documentation for a class, QDoc will create and link to a separate page documenting its obsolete functions. Usually an equivalent function is provided as an alternative.

      / *!
          \fn MyClass::MyObsoleteFunction
          \obsolete

          Use MyNewFunction() instead.
      * /

QDoc renders this in `myclass-obsolete.html` as:

> # Obsolete Members for MyClass

> The following class members are obsolete. They are provided to keep old source code working. We strongly advise against using them in new code.

> ...

> - void MyObsoleteFunction() `(obsolete)`
> - ...

> ## Member Function Documentation

> ### void MyObsoleteFunction ()

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

## \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)`
> - ...

## \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().

QDoc generates the "Qt" reference from the `project` configuration variable. For that reason this reference will change according to the current documentation project.

See also `project`.

Document Navigation ◦ Thread Support