|
|
| Line 1: |
Line 1: |
| [[Category:Writing Guidelines]] | | [[Category:Writing Guidelines]] |
|
| |
|
| = QML Documentation Style =
| | * |
| This page is part of the [[QtWritingGuidelines| Qt Writing Guidelines]].
| |
| | |
| Though there are exceptions, these guidelines should be followed. Keeping that in mind, at least '''be consistent within the page'''. Meaning, the class member documentation should have the same style.
| |
| | |
| QDoc can process QML types defined as C++ classes and QML types defined in ''.qml'' files. For C++ classes documented as QML types, the QDoc comments are in the ''.cpp'' file while QML types defined in QML are in the ''.qml'' file. The C++ classes must also be documented with the QML [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html topic commands]:
| |
| | |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlattachedproperty-command \qmlattachedproperty] | |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlattachedsignal-command \qmlattachedsignal]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmltype-command \qmltype]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlmethod-command \qmlmethod]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlproperty-command \qmlproperty]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlsignal-command \qmlsignal]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlmodule-command \qmlmodule]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#inqmlmodule-command \inqmlmodule]
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#instantiates-command \instantiates]
| |
| | |
| For QML types defined in ''.qml'' files, QDoc will parse the QML and determine the properties, signals, and the type within the QML definition. The QDoc
| |
| block then needs to be immediately above the declaration. For QML types implemented in C++'', QDoc will output warnings if the C''+ class documentation does not exist.
| |
| | |
| == QML Module Versions ==
| |
| | |
| QDoc considers the version specified in the '''\qmlmodule''' command as the import statement. Types which belong to the module do not need to specify the version, only the module name.
| |
| | |
| <code>
| |
| | |
| /*!
| |
| \qmlmodule QtQuick.Controls 1.1
| |
| #this is the same as the import statement. You don't need to specify the version number since Qt 6.2
| |
| */
| |
| | |
| /*!
| |
| \qmltype Button
| |
| \inqmlmodule QtQuick.Controls
| |
| #QDoc will associate this Button to whatever version QtQuick.Controls has. (only one version per release)
| |
| */
| |
| </code>
| |
| | |
| There are two versions important for the user to know: Qt version and QML module version.
| |
| | |
| Use:
| |
| | |
| * '''\since 5.3''' - for ''\qmltype''
| |
| * '''\since <qml module> <version>''' - for \qmlproperty and the members.
| |
| * '''\since QtQuick 2.3''' - in a property documentation block will generate: ''This property was introduced in QtQuick 2.3''
| |
| | |
| == QML Types ==
| |
| | |
| The [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmltype-command \qmltype] command is for QML type documentation.
| |
| | |
| <code>
| |
| /*!
| |
| \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
| |
| */
| |
| </code>
| |
| | |
| Some commonly used commands and [http://doc-snapshots.qt.io/qt5-dev/14-qdoc-commands-contextcommands.html context commands]:
| |
| * [https://doc-snapshots.qt.io/qt6-dev/11-qdoc-commands-specialcontent.html#brief-command \brief] - the brief description '''mandatory'''
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#inqmlmodule-command \inqmlmodule] '''mandatory'''
| |
| * [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#instantiates-command \instantiates] - accepts the C++ class which implements the QML type as the argument. For types implemented in QML, this is not needed.
| |
| * [https://doc-snapshots.qt.io/qt6-dev/16-qdoc-commands-status.html#since-command \since] - Add the Qt version the type was introduced in. '''mandatory''' (see '''Note:''' below about backdating APIs)
| |
| | |
| '''Note:''' It was decided that we will not backdate APIs, so only add the with the version number of an upcoming release. See https://codereview.qt.io/#change,43797
| |
| | |
| The '''brief description''' provides a summary for the QML type. The brief does not need to be a complete sentence and may start with a verb. QDoc will append the brief description onto the QML type in tables and generated lists. '''Don't forget the period at the end.'''
| |
| | |
| <code>
| |
| \qmltype ColorAnimation
| |
| \brief Animates changes in color values.
| |
| </code>
| |
| | |
| Here are some alternate verbs for the brief statement:
| |
| | |
| * "Provides…"
| |
| * "Specifies…"
| |
| * "Describes…"
| |
| | |
| The '''detailed description''' follows the brief and may contain images, snippet, and link to other documentation.
| |
| | |
| == Properties ==
| |
| | |
| The property description focuses on what the property ''does''. Property documentation usually starts with "This property…" but for certain properties, these are the common expressions:
| |
| | |
| * "This property holds…"
| |
| * "This property describes…"
| |
| * "This property represents…"
| |
| * "Returns true when… and false when…" - for properties that are marked ''read-only''.
| |
| * "Sets the…" - for properties that configure a type.
| |
| | |
| == Aliases ==
| |
| | |
| The QDoc parser cannot guess the type of the alias, therefore, the type must be fully documented with the [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlproperty \qmlproperty] command.
| |
| | |
| == Signals and Handlers Documentation ==
| |
| | |
| QML signals are documented either in the QML file or in the C++ implementation with the [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlsignal-command \qmlsignal] command. Signal documentation must include the condition for emitting the signal, mention the corresponding signal handler, and document whether the signal accepts a parameter.
| |
| | |
| <code>
| |
| /*
| |
| 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
| |
| onClicked.
| |
| */
| |
| </code>
| |
| | |
| These are the possible documentation styles for signals:
| |
| | |
| * "This signal is triggered when…"
| |
| * "Triggered when…"
| |
| * "Emitted when…"
| |
| | |
| == Read-Only Properties ==
| |
| | |
| To mark that a property is a ''read-only'' property, add the \readonly command to the property documentation. QDoc then notes that the property is a read-only property.
| |
| | |
| For properties that are declared in QML files with the '''readonly''' keyword, QDoc can detect that it is a read-only property and will automatically add the read-only marking.
| |
| | |
| == Methods and JavaScript Functions ==
| |
| | |
| Typically, function documentation immediately precedes the implementation of the function in the ''.cpp'' file. The [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html topic command] for functions is [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlmethod-command \qmlmethod]. For functions in QML or JavaScript, the documentation must reside immediately above the function declaration.
| |
| | |
| The function documentation starts with a verb, indicating the operation the function performs.
| |
| | |
| <code>
| |
| /*!
| |
| \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)
| |
| </code>
| |
| | |
| Some common verbs for function documentation:
| |
| | |
| * "Copies…" - for constructors
| |
| * "Destroys…" - for destructors
| |
| * "Returns…" - for accessor functions
| |
| | |
| The function documentation must document:
| |
| | |
| * the return type
| |
| * the parameters
| |
| * the actions of the functions
| |
| | |
| The [https://doc-snapshots.qt.io/qt6-dev/04-qdoc-commands-textmarkup.html#a-command \a] command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the [https://doc-snapshots.qt.io/qt6-dev/04-qdoc-commands-textmarkup.html#c-command \c] command in the case of Boolean values.
| |
| | |
| == Enumerations ==
| |
| | |
| QML enumerations are documented as QML properties with the [https://doc-snapshots.qt.io/qt6-dev/13-qdoc-commands-topics.html#qmlproperty-command \qmlproperty] command. The type of the property is ''enumeration''.
| |
| | |
| <code>
| |
| /*!
| |
| \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
| |
| | |
| \qml
| |
| Text { text: "Hello"; font.weight: Font.DemiBold }
| |
| \endqml
| |
| */
| |
| </code>
| |
| | |
| To begin the description, use:
| |
| | |
| * "This enumeration…"
| |