Стиль документации 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++.