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