Статус

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

\abstract и \qmlabstract

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

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

\compat

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

Команда должна стоять на отдельной строке.

Обычно предоставляется эквивалентная функция или класс в качестве альтернативы.

Если команда используется в документации класса, команда расширяется в предупреждение о том, что указанный класс является частью библиотеки поддержки. Предупреждение расположено в верхней части страницы документации.

\beginqdoc
    \class MyQt3SupportClass
    \compat
\endqdoc

QDoc отображает это в верхней части страницы справки класса MyQt3SupportClass.

Этот класс является частью библиотеки поддержки Qt 3. Он предоставляется для сохранения работоспособности старого исходного кода. Мы настоятельно рекомендуем не использовать его в новом коде. См. Руководство по переносу для получения дополнительной информации.

Если команда используется при документировании функции, QDoc создаст и ссылается на отдельную страницу, документирующую члены поддержки Qt 3, при генерации справочной документации для соответствующего класса.

\beginqdoc
    \fn MyClass::MyQt3SupportMemberFunction
    \compat

    Use MyNewFunction() instead.
\endqdoc

QDoc отображает это в myclass-qt3.html как:

Члены поддержки Qt 3 для MyClass

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

...

• void MyQt3SupportMemberFunction()
• ...

---

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

void MyQt3SupportMemberFunction ()

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

...

\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 отображает это свойство на странице справки для типа State.

\obsolete

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

Команда должна стоять на отдельной строке.

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

/ *!
    \fn MyClass::MyObsoleteFunction
    \obsolete

    Use MyNewFunction() instead.
* /

QDoc отображает это в myclass-obsolete.html как:

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

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

...

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

---

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

void MyObsoleteFunction ()

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

...

\internal

Команда \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 расширяется до уведомления в документации функции и помечает функцию как предварительную, когда она появляется в списках.

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

\since

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