Статус

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

\abstract и \qmlabstract

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

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

\default

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

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

Если значение по умолчанию является непустой строкой, используйте кавычки:

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\qmldefault

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

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

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

\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 устарела и заменена командой \deprecated.

Эта команда сохраняется только для обеспечения обратной совместимости. Она может быть удалена в будущей версии QDoc. Используйте команду \deprecated вместо неё.

См. также \deprecated.

\deprecated

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

Команда \deprecated принимает два необязательных аргумента:

• Версия в квадратных скобках (например, [6.2]).
• Строка с дополнительной информацией, например, предложенная замена.

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

/ *!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
* /

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

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

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

...

• void MyDeprecatedFunction() (deprecated)
• ...

---

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

void MyDeprecatedFunction ()

Эта функция устарела начиная с версии 6.2. Она предоставляется для обеспечения работы старого исходного кода. Мы настоятельно рекомендуем не использовать её в новом коде. Используйте 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;
}

Эта функция не будет включена в документацию, если QDoc не вызывается с опцией командной строки -showinternal или переменная окружения QDOC_SHOW_INTERNAL установлена.

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

\readonly

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

\required

Команда \required используется совместно с командой \qmlproperty для маркировки свойства QML как обязательного.

См. также Система свойств.

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