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