Style de documentation QML

QDoc peut traiter les types QML définis comme des classes C++ et les types QML définis dans les fichiers .qml. Pour les classes C++ documentées en tant que types QML, les commentaires QDoc se trouvent dans le fichier .cpp, tandis que les types QML définis dans QML se trouvent dans le fichier .qml. Les classes C++ doivent également être documentées à l'aide des commandes de thème QML :

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \nativetype

Pour les types QML définis dans les fichiers .qml, QDoc analysera le QML et déterminera les propriétés, les signaux et le type dans la définition QML. Le bloc QDoc doit alors être placé immédiatement au-dessus de la déclaration. Pour les types QML implémentés en C++, QDoc émettra des avertissements si la documentation de la classe C++ n'existe pas. La documentation de la classe peut être marquée comme interne s'il ne s'agit pas d'une API publique.

Types QML

La commande \qmltype est destinée à la documentation des types QML.

    \qmltype TextEdit
    \nativetype 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}

La commande \nativetype accepte comme argument la classe C++ qui implémente le type QML. Pour les types implémentés en QML, cela n'est pas nécessaire.

La brève description fournit un résumé du type QML. La brève description ne doit pas nécessairement être une phrase complète et peut commencer par un verbe. QDoc ajoutera la brève description au type QML dans les tableaux et les listes générées.

\qmltype ColorAnimation
\brief Animates changes in color values

Voici quelques verbes alternatifs pour la brève description :

• "Fournit..."
• "Spécifie..."
• "Décrit..."

La description détaillée suit la brève et peut contenir des images, des extraits et des liens vers d'autres documents.

Propriétés

La description de la propriété se concentre sur ce que fait la propriété et peut utiliser le style suivant :

La documentation sur les biens commence généralement par "Ce bien...", mais pour certains biens, les expressions suivantes sont courantes :

• "Cette propriété détient..."
• "Cette propriété décrit..."
• "Cette propriété représente..."
• "Renvoie true lorsque... et false lorsque..." - pour les propriétés marquées read-only.
• "Définit le..." - pour les propriétés qui configurent un type.

Documentation sur les signaux et les gestionnaires

Les signaux QML sont documentés soit dans le fichier QML, soit dans l'implémentation C++ avec la commande \qmlsignal dans l'implémentation C++. La documentation des signaux doit inclure la condition d'émission du signal, mentionner le gestionnaire de signal correspondant et indiquer si le signal accepte un paramètre.

/*
    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()

Voici les styles de documentation possibles pour les signaux :

• "Ce signal est déclenché lorsque..."
• "Déclenché lorsque..."
• "Émis lorsque..."

Méthodes et fonctions QML

En règle générale, la documentation relative aux fonctions précède immédiatement la mise en œuvre de la fonction dans le fichier .cpp. La commande topic pour les fonctions est \fn. Pour les fonctions en QML, la documentation doit se trouver immédiatement au-dessus de la déclaration de la fonction.

La documentation de la fonction commence par un verbe, qui indique l'opération effectuée par la fonction.

/*
    \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)

Voici quelques verbes courants pour la documentation d'une fonction :

• "Copie..." - pour les constructeurs
• "Détruit..." - pour les destructeurs
• "Retourne..." - pour les fonctions d'accès

La documentation de la fonction doit documenter

• le type de retour
• les paramètres
• les actions des fonctions

La commande \a marque le paramètre dans la documentation. La documentation du type de retour doit être liée à la documentation du type ou être marquée par la commande \c dans le cas de valeurs booléennes.

Les énumérations

Les énumérations QML sont documentées comme des propriétés QML avec la commande \qmlenum avec la commande Utilisez la commande \value pour documenter les valeurs de l'énumération. Ajoutez le nom du type comme préfixe à chaque valeur, séparé par un point (.), car QDoc ne le fait pas automatiquement.

/*!
\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

Le commentaire QDoc énumère les valeurs de l'énumération.

Si l'énumération est implémentée en C++, envisagez d'utiliser la commande \qmlenumeratorsfrom . Si ce n'est pas possible, la documentation peut également établir un lien direct avec l'énumération C++ correspondante. Toutefois, le commentaire QDoc doit alors indiquer que l'énumération est une énumération C++.