Стиль документации QML

QDoc может обрабатывать типы QML, определённые как классы C++, и типы QML, определённые в файлах .qml. Для классов C++, документированных как типы QML, комментарии QDoc находятся в файле .cpp, а типы QML, определённые в QML, — в файле .qml. Классы C++ также должны быть документированы с помощью команд QML темы:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlbasictype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \instantiates

Для типов QML, определённых в файлах .qml, QDoc проанализирует QML и определит свойства, сигналы и тип в определении QML. Блок QDoc должен находиться непосредственно над объявлением. Для типов QML, реализованных в C++, QDoc выведет предупреждения, если документация класса C++ отсутствует. Документация класса может быть помечена как внутренняя, если она не является частью публичного API.

Типы QML

Команда \qmltype предназначена для документирования типов QML.

    \qmltype TextEdit
    \instantiates QQuickTextEdit
    \inqmlmodule QtQuick
    \ingroup qtquick-visual
    \ingroup qtquick-input
    \inherits Item
    \brief Displays multiple lines of editable formatted text

    The TextEdit item displays a block of editable, formatted text.

    It can display both plain and rich text. For example:

    \qml
        TextEdit {
            width: 240
            text: "<b>Hello</b> <i>World!</i>"
            font.family: "Helvetica"
            font.pointSize: 20
            color: "blue"
            focus: true
        }
    \endqml

    \image declarative-textedit.gif

    ... omitted detailed description

    \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}

Команда \instantiates принимает класс C++, который реализует тип QML, в качестве аргумента. Для типов, реализованных в QML, это не требуется.

Краткое описание предоставляет сводку для типа QML. Краткое описание не должно быть полным предложением и может начинаться с глагола. QDoc добавит краткое описание к типу QML в таблицах и сгенерированных списках.

\qmltype ColorAnimation
\brief Animates changes in color values

Вот некоторые альтернативные глаголы для краткого описания:

• "Предоставляет..."
• "Определяет..."
• "Описывает..."

Подробное описание следует за кратким и может содержать изображения, фрагменты кода и ссылки на другую документацию.

Свойства

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

Документация свойства обычно начинается с «Это свойство...», но для определённых свойств используются следующие выражения:

• "Это свойство содержит..."
• "Это свойство описывает..."
• "Это свойство представляет..."
• "Возвращает true при... и false при... » — для свойств, помеченных read-only.
• "Устанавливает..." — для свойств, которые конфигурируют тип.

Документация сигналов и обработчиков

Сигналы QML документируются либо в файле QML, либо в реализации C++ с помощью команды \qmlsignal. Документация сигнала должна включать условие для отправки сигнала, упоминание соответствующего обработчика сигнала и документацию о том, принимает ли сигнал параметр.

/*
    This signal is emitted when the user clicks the button. A click is defined
    as a press followed by a release. The corresponding handler is
    \c onClicked.
*/
signal clicked()

Возможные стили документации для сигналов:

• "Этот сигнал срабатывает при..."
• "Срабатывает при..."
• "Выполняется при..."

Методы и функции JavaScript

Как правило, документация функции находится непосредственно перед реализацией функции в файле .cpp. Команда темы для функций — \fn. Для функций в QML или JavaScript документация должна находиться непосредственно над объявлением функции.

Документация функции начинается с глагола, указывающего операцию, которую выполняет функция.

/*
    \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)

    Deletes the content at \a index from the model.

    \sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)

Некоторые общие глаголы для документации функций:

• "Копирует..." — для конструкторов
• "Удаляет..." — для деструкторов
• "Возвращает..." — для функций-доступов

Документация функции должна описывать:

• тип возвращаемого значения
• параметры
• действия функций

Команда \a помечает параметр в документации. Документация типа возвращаемого значения должна ссылаться на документацию типа или быть помечена командой \c в случае булевых значений.

Перечисления

Перечисления QML документируются как свойства QML с помощью команды \qmlproperty. Тип свойства — enumeration. Используйте команду \value для документирования значений перечисления. Добавьте имя типа в качестве префикса к каждому значению, разделенному точкой (.), так как QDoc этого не делает автоматически.

/*!
\qmlproperty enumeration QtQuick2::Text::font.weight

Sets the font's weight.

The weight can be one of:
\value Font.Light
\value Font.Normal      The default
\value Font.DemiBold
\value Font.Bold
\value Font.Black

В комментарии QDoc перечислены значения перечисления. Если перечисление реализовано в C++, документация может ссылаться на соответствующее перечисление C++. Однако комментарий QDoc должен указывать, что перечисление является перечислением C++.