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