Стили руководства по документации 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.

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

Sets the font's weight.

The weight can be one of:
\list
\li Font.Light
\li Font.Normal - the default
\li Font.DemiBold
\li Font.Bold
\li Font.Black
\endlist
*/

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