Статус

Эти команды предназначены для указания того, что документированный элемент имеет особый статус. Элемент может быть помечен как устаревающий или просто не должен включаться в публичный интерфейс. Команда \since используется для указания номера версии, в которой функция или класс впервые появились. Команда \qmlabstract используется для пометки типа QML как абстрактного базового класса.

\abstract и \qmlabstract

\abstract является синонимом команды \qmlabstract. Добавьте эту команду в комментарий \qmltype для типа QML, когда этот тип предназначен только для использования в качестве абстрактного базового типа. Когда тип QML является абстрактным, это означает, что тип QML не может быть инстанцирован. Вместо этого свойства в его публичном API включаются в список публичных свойств на странице справки для каждого типа QML, который наследует абстрактный тип QML. Свойства документируются так, как если бы они были свойствами наследуемого типа QML.

Обычно, когда тип QML помечен с помощью \qmlabstract, он также помечен с помощью \internal, чтобы его страница справки не генерировалась. Если абстрактный тип QML не помечен как внутренний, у него будет страница справки в документации.

\default

Команда \default предназначена для пометки свойства QML как свойства по умолчанию. В документации свойства отображается слово default.

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

Посмотрите, как QDoc отображает это свойство на странице справки для типа Состояние.

\dontdocument

Команда \dontdocument используется только в файле dontdocument.qdoc для конкретного модуля. Этот файл указывает публично объявленные классы или структуры, которые не предназначены для документирования. QDoc не будет выводить предупреждения об отсутствующих комментариях \class для этих классов и структур.

Ниже вы найдете команду \dontdocument в файле dontdocument.qdoc для виджетов:

/ *!
   \dontdocument (QTypeInfo QMetaTypeId)
* /

\inheaderfile

Метакоманда \inheaderfile используется для переопределения оператора include, генерируемого для документации ссылок на C++-класс, пространство имен или заголовочный файл.

По умолчанию QDoc документирует \class SomeClass как доступный с последующим оператором include:

#include <SomeClass>

Если фактический оператор include отличается от значения по умолчанию, это можно документировать как

\class SomeClass
\inheaderfile Tools/SomeClass
...

См. также \class и \headerfile.

\устаревшее

Команда \obsolete предназначена для указания того, что функция устарела и больше не должна использоваться в новом коде. Нет никакой гарантии, как долго она будет оставаться в библиотеке.

Команда \obsolete не принимает аргументов.

При генерации документации справки для класса QDoc создаст и свяжет отдельную страницу, документирующую его устаревшие функции. Обычно предоставляется эквивалентная функция в качестве альтернативы.

/ *!
    \fn MyClass::MyObsoleteFunction
    \obsolete

    Use MyNewFunction() instead.
* /

QDoc отображает это в myclass-obsolete.html следующим образом:

Устаревшие члены для MyClass

Следующие члены класса устарели. Они предоставляются для сохранения работы старого исходного кода. Мы настоятельно рекомендуем не использовать их в новом коде.

...

• void MyObsoleteFunction() (obsolete)
• ...

---

Документация функций-членов

void MyObsoleteFunction ()

Используйте MyNewFunction() вместо этого.

...

\внутренний

Команда \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;
}

Эта функция не будет включена в документацию.

\предварительный

Команда \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);
}

QDoc отображает это как:

JoiningType QChar::joiningType() const

Эта функция находится в стадии разработки и может быть изменена.

Возвращает информацию о характеристиках типа соединения символа (необходимая для некоторых языков, таких как арабский или сирийский).

И запись функции в списке публичных функций QChar будет отображаться как:

• ...
• JoiningType joiningType() const (preliminary)
• ...

\только для чтения

Команда \readonly используется совместно с командой \qmlproperty для пометки свойства QML как только для чтения.

\с

Команда \since указывает, в какой малой версии была добавлена связанная функциональность.

/ *!
    \since 4.1

    Returns an icon for \a standardIcon.

    ...

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

QDoc отображает это как:

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

Эта функция была введена в Qt версии 4.1

Возвращает значок для standardIcon.

...

См. также standardPixmap().

QDoc генерирует ссылку "Qt" из переменной конфигурации project. По этой причине эта ссылка будет меняться в зависимости от текущего проекта документации.

См. также project.