Style de documentation QML

QDoc peut traiter les types QML définis comme des classes C++ ainsi que les types QML définis dans des 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 en QML se trouvent dans le fichier « .qml ». Les classes C++ doivent également être documentées à l’aide des commandes de rubrique QML :

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

Pour les types QML définis dans les fichiers .qml, QDoc analysera le code QML et déterminera les propriétés, les signaux et le type au sein de la définition QML. Le bloc QDoc doit alors se trouver 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 \qmltype commande sert à 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 \nativetype commande prend en 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 description succincte fournit un résumé du type QML. Elle n'a pas besoin d'être une phrase complète et peut commencer par un verbe. QDoc ajoutera cette description succincte 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 de code et des liens vers d'autres documents.

Propriétés

La description d’une propriété met l’accent sur son fonctionnement et peut adopter le style suivant :

La documentation d'une propriété commence généralement par « Cette propriété… », mais pour certaines propriétés, voici les expressions couramment utilisées :

• « Cette propriété contient… »
• « Cette propriété décrit… »
• « Cette propriété représente… »
• « Renvoie true lorsque… et false lorsque… » – pour les propriétés marquées comme « 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++ à l’aide de la \qmlsignal commande. La documentation d’un signal 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 d’une fonction précède immédiatement l’implémentation de celle-ci dans le fichier d’ .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, indiquant 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 utilisés dans la documentation des fonctions :

• « Copie… » — pour les constructeurs
• « Destruit... » – pour les destructeurs
• « Renvoie... » – pour les fonctions d'accès

La documentation de la fonction doit préciser :

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

La \a commande permet de mettre en évidence le paramètre dans la documentation. La documentation relative au type de retour doit renvoyer vers la documentation du type ou être mise en évidence à l'aide de la \c commande dans le cas de valeurs booléennes.

Énumérations

Les énumérations QML sont documentées en tant que propriétés QML à l’aide de la \qmlenum commande. Utilisez la \value commande pour documenter les valeurs de l'énumération. Ajoutez le nom du type en 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 répertorie les valeurs de l’énumération.

Si l’énumération est implémentée en C++, pensez à utiliser la \qmlenumeratorsfrom commande. Si cela n'est pas possible, la documentation peut également renvoyer directement à l'énumération C++ correspondante. Toutefois, le commentaire QDoc doit alors préciser qu'il s'agit d'une énumération C++.