View source for QMLDocumentationStyle

[[Category:Writing Guidelines]]
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}

= 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 documented with the QML [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html topic commands]:

* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlattachedproperty-command \qmlattachedproperty]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlattachedsignal-command \qmlattachedsignal]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmltype-command \qmltype]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlmethod-command \qmlmethod]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlproperty-command \qmlproperty]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlsignal-command \qmlsignal]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlmodule-command \qmlmodule]
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#inqmlmodule-command \inqmlmodule]
* [http://doc-snapshots.qt.io/qt5-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 command as the import statement. Types which belong to the module do not need to specify the version, only the module name.

<code>

/*!
 QtQuick.Controls 1.1
 #this is the same as the import statement

*/

/*!
 Button
 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
''' "5.3" for  "<qml module> <version>" for and the members.

"QtQuick 2.3" in a property documentation block will generate: "This property was introduced in QtQuick 2.3"

== QML Types ==

The [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmltype-command \qmltype] command is for QML type documentation.

<code>
 TextEdit
 QQuickTextEdit
 QtQuick
 4.8
 qtquick-visual
 qtquick-input
 Item
 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:

TextEdit {
 width: 240
 text: "<b>Hello</b> <i>World!</i>"
 font.family: "Helvetica"
 font.pointSize: 20
 color: "blue"
 focus: true
 }
 

declarative-textedit.gif

… omitted detailed description

Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
</code>

Some commonly used commands and [http://doc-snapshots.qt.io/qt5-dev/14-qdoc-commands-contextcommands.html context commands]:
* [http://doc-snapshots.qt.io/qt5-dev/11-qdoc-commands-specialcontent.html#brief-command \brief] - the brief description '''mandatory'''
* [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#inqmlmodule-command \inqmlmodule] '''mandatory'''
* [http://doc-snapshots.qt.io/qt5-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.
* [http://doc-snapshots.qt.io/qt5-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>
ColorAnimation
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 rue when… and alse 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 [http://doc-snapshots.qt.io/qt5-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 [http://doc-snapshots.qt.io/qt5-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
 nClicked.
*/
</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, typethe * command in 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 [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html topic command] for functions is [http://doc-snapshots.qt.io/qt5-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>
/*
 QtQuick2::ListModel::remove(int index, int count = 1)

Deletes the content at index from the model.

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 [http://doc-snapshots.qt.io/qt5-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 [http://doc-snapshots.qt.io/qt5-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 [http://doc-snapshots.qt.io/qt5-dev/13-qdoc-commands-topics.html#qmlproperty-command \qmlproperty] command. The type of the property is ''enumeration''.

<code>
/*!
enumeration QtQuick2::Text::font.weight

Sets the font's weight.

The weight can be one of:

Font.Light
Font.Normal - the default
Font.DemiBold
Font.Bold
Font.Black
*/
</code>

To begin the description, use:
''' "This enumeration…"