Catégories de documentation

Il existe plusieurs types de catégories ou types de documentation prédéfinis :

• Article
• Documentation de l'API C++
• Documentation de type QML
• Exemple de code

QDoc a la capacité de formater une page en fonction du type. En outre, les feuilles de style peuvent fournir un contrôle supplémentaire sur l'affichage de chaque catégorie.

Documentation de l'API

QDoc excelle dans la création de documentation d'API à partir d'un ensemble de code source et de documentation dans les commentaires QDoc. Plus précisément, QDoc connaît l'architecture de Qt et peut valider l'existence de la documentation sur les classes, les fonctions ou les propriétés de Qt C++. QDoc émet des avertissements et des erreurs s'il ne peut pas associer une documentation à une entité de code ou si une entité de code n'a pas de documentation.

En général, chaque entité de code Qt telle que les propriétés, les classes, les méthodes, les signaux et les énumérations a une commande topic correspondante. QDoc associera la documentation à la source en utilisant les règles de nommage du C++.

QDoc analysera les fichiers d'en-tête (généralement des fichiers .h ) pour construire une arborescence des structures de classe. Ensuite, QDoc analysera les fichiers source et les fichiers de documentation pour attacher la documentation à la structure de classe. Enfin, QDoc génère une page pour la classe.

Styles de langue

Pour produire une documentation de qualité sur l'API, les références de l'API Qt suivent des directives linguistiques particulières. Alors que le contenu de cette page montre comment créer la documentation de l'API, les directives de style montrent comment les documents de référence suivent une utilisation cohérente du langage.

• Style de documentation C++
• Style de documentation QML

Documentation des types QML

Dans le monde de QML, il existe des entités supplémentaires que nous devons documenter, telles que les signaux QML, les propriétés attachées et les méthodes QML. En interne, ces entités utilisent les technologies Qt, mais la documentation de l'API QML nécessite une mise en page et des conventions de nommage différentes de celles de la documentation de l'API C++ de Qt.

Liste des commandes QDoc relatives à QML :

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - crée une documentation de type QML
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

Pour documenter un type QML, commencez par créer un commentaire QDoc qui utilise la commande \qmltype comme commande de sujet.

Analyseur QML

Si votre type QML est défini dans un fichier qml, documentez-le dans ce fichier. Si votre type QML est représenté par une classe C++, documentez-le dans le fichier cpp de cette classe C++ et incluez une commande \nativetype pour spécifier le nom de la classe C++. Ne documentez pas un type QML dans un fichier cpp si le type QML est défini dans un fichier qml.

Lorsque vous documentez un type QML dans un fichier qml, placez chaque commentaire QDoc directement au-dessus de l'entité à laquelle le commentaire s'applique. Par exemple, placez le commentaire QDoc contenant la commande \qmltype (le commentaire du sujet) directement au-dessus du type QML extérieur dans le fichier qml. Placez le commentaire pour documenter une propriété QML directement au-dessus de la déclaration de la propriété, et ainsi de suite pour les gestionnaires de signaux QML et les méthodes QML. Notez que lorsque vous documentez des propriétés QML dans un fichier qml, vous n'incluez normalement pas la commande \qmlproperty en tant que commande de sujet (ce que vous devez faire lorsque vous documentez des types QML dans des fichiers cpp ), car l'analyseur QML associe automatiquement chaque commentaire QDoc à la déclaration QML suivante qu'il analyse. Il en va de même pour les commentaires des gestionnaires de signaux et des méthodes QML. Mais il est parfois utile d'inclure une ou plusieurs commandes dans le commentaire. \qmlproperty dans le commentaire, par exemple lorsque le type de propriété est un autre type QML et que vous souhaitez que l'utilisateur n'utilise que certaines propriétés de cet autre type QML, mais pas toutes. Mais lorsque vous documentez une propriété qui a un alias, placez le commentaire QDoc correspondant directement au-dessus de la déclaration de l'alias. Dans ce cas, le commentaire QDoc doit contenir une commande \qmlproperty car c'est la seule façon pour QDoc de connaître le type de la propriété aliasée.

Lorsque vous documentez un type QML dans le fichier cpp de la classe C++ correspondante (s'il y en a une), vous placez normalement chaque commentaire QDoc directement au-dessus de l'entité qu'il documente. Cependant, QDoc n'utilise pas l'analyseur QML pour analyser ces fichiers (l'analyseur C++ est utilisé), de sorte que ces commentaires QML QDoc peuvent apparaître n'importe où dans le fichier cpp. Notez que les commentaires QML QDoc dans les fichiers cpp doivent utiliser les commandes de sujet QML, c'est-à-dire que la commande \qmltypedoit apparaître dans le commentaire QDoc pour le type QML, et une commande \qmlpropertydoit apparaître dans chaque commentaire QDoc de propriété QML.

Modules QML

Un type QML appartient à un module. Le module peut inclure tous les types apparentés pour une plate-forme ou contenir une certaine version de Qt Quick. Par exemple, les types Qt Qml Qt Quick 2 appartiennent au module Qt Quick 2, tandis qu'il existe également un module Qt Quick 1 pour les types plus anciens introduits dans Qt 4.

Les modules QML permettent de regrouper les types QML. La commande \qmltype topic doit être accompagnée d'une commande \inqmlmodule pour relier le type à un module QML. De même, une commande \qmlmodule topic doit exister dans un fichier .qdoc distinct pour créer la page de présentation du module. La page de présentation énumère les types QML du module QML.

Les liens vers les types QML doivent donc également contenir le nom du module. Par exemple, si un type appelé TabWidget se trouve dans le module UIComponents, il doit être lié à UIComponents::TabWidget.

Propriétés QML en lecture seule et internes

QDoc détecte les propriétés QML marquées comme readonly. Notez que la propriété doit être initialisée avec une valeur.

readonly property int sampleReadOnlyProperty: 0

Les propriétés et les signaux qui ne sont pas destinés à l'interface publique peuvent être marqués avec la commande \internal . QDoc ne publiera pas la documentation dans les résultats générés.

Articles et aperçus

Les articles et les aperçus sont un style d'écriture utilisé de préférence pour fournir des détails sommaires sur un sujet ou un concept. Ils peuvent présenter une technologie ou discuter de la manière dont un concept peut être appliqué, mais sans discuter des étapes exactes de manière trop détaillée. Toutefois, ce type de contenu peut servir de point d'entrée aux lecteurs pour trouver des documents d'instruction et de référence, tels que des didacticiels, des exemples et de la documentation sur les cours. Un exemple de vue d'ensemble pourrait être une page de produit, telle qu'une discussion de haut niveau sur Qt Quick, des modules individuels, des principes de conception ou des outils.

Pour indiquer qu'un document est un article, vous ajoutez le mot-clé article à la commande \page:

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

La section consacrée aux commandes d'écriture de rubriques contient une liste des arguments disponibles pour la commande \page.

Exemples de code

Les exemples sont un moyen efficace de démontrer l'utilisation pratique d'une technologie ou d'un concept donné. En ce qui concerne les intergiciels, ils prennent généralement la forme d'une application utilisant un code simple et des explications claires sur ce que fait le code. Tout module, API, projet, modèle, etc. devrait avoir au moins un bon exemple.

Un exemple peut être accompagné d'un tutoriel. Le didacticiel explique et décrit le code, tandis que l'exemple de code est le contenu du code que les utilisateurs peuvent étudier. Les exemples de code peuvent être accompagnés d'un texte qui ne figure pas dans le didacticiel.

QDoc créera une page contenant l'exemple de code avec une description à l'aide de la commande \example pour créer une page contenant l'exemple de code et une description.

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc utilisera le répertoire spécifié dans la variable input exampledirs pour trouver le fichier Qt Project (.pro) afin de générer les fichiers d'exemple. Le code HTML généré portera le nom de fichier declarative-ui-components-tabwidget.html. QDoc énumérera également tout le code de l'exemple.