Catégories de documentation

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

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

QDoc permet de mettre en forme une page en fonction de son type. De plus, des feuilles de style permettent de contrôler davantage 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 contenue dans les commentaires QDoc. Plus précisément, QDoc connaît l'architecture de Qt et peut vérifier l'existence de la documentation des classes, fonctions ou propriétés C++ de Qt. QDoc génère des avertissements et des erreurs s'il ne parvient pas à associer une documentation à une entité de code ou si une entité de code ne dispose 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, dispose d’une commande de rubrique correspondante. QDoc associera la documentation au code source en utilisant les règles de nommage C++.

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

Styles linguistiques

Afin de produire une documentation API de qualité, les références de l’API Qt suivent des directives linguistiques spécifiques. Alors que le contenu de cette page explique comment créer de la documentation API, les directives stylistiques montrent comment les documents de référence respectent une utilisation cohérente de la langue.

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

Documentation des types QML

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

Liste des commandes QDoc liées au QML :

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

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

Analyseur QML

Si votre type QML est défini dans un fichier qml, documentez-le à cet endroit. Si votre type QML est représenté par une classe C++, documentez-le dans le fichier cpp correspondant à cette classe C++ et incluez une \nativetype commande pour spécifier le nom de la classe C++. Ne documentez pas un type QML dans un fichier cpp si ce 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 il s'applique. Par exemple, placez le commentaire QDoc contenant la \qmltype commande (le commentaire de rubrique) directement au-dessus du type QML externe dans le fichier qml. Placez le commentaire documentant 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 \qmlproperty commande en tant que commande de rubrique (ce que vous devez faire lorsque vous documentez des types QML dans des fichiers C++ ), 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 relatifs aux gestionnaires de signaux QML et aux méthodes QML. Cependant, il est parfois utile d’inclure une ou plusieurs \qmlproperty commandes dans le commentaire, par exemple lorsque le type de la 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, et non toutes. En revanche, lorsque vous documentez une propriété qui possède un alias, placez le commentaire QDoc correspondant directement au-dessus de la déclaration de l’alias. Dans ces cas-là, le commentaire QDoc doit contenir une \qmlproperty commande, 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 sa classe C++ correspondante (s’il en possède 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 (c’est l’analyseur C++ qui est utilisé) ; ces commentaires QDoc QML peuvent donc apparaître n’importe où dans le fichier .cpp. Notez que les commentaires QDoc QML dans les fichiers .cpp doivent utiliser les commandes de rubrique QML. Autrement dit, la \qmltypedoit figurer dans le commentaire QDoc du type QML, et une commande \qmlproperty commande doit 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 associés à une plateforme ou contenir une version spécifique de Qt Quick. Par exemple, les types QML de « 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 des types QML. La \qmltype commande « topic » doit comporter une \inqmlmodule commande « context » pour associer le type à un module QML. De même, une \qmlmodule commande « topic » doit exister dans un fichier « .qdoc » distinct pour créer la page de présentation du module. Cette page répertorie les types QML du module.

Les liens vers les types QML doivent donc également contenir le nom du module. Par exemple, si un type nommé TabWidget se trouve dans le module UIComponents, il doit être lié sous la forme 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 à l’aide de la \internal commande. QDoc ne publiera pas la documentation dans les fichiers de sortie générés.

Articles et présentations générales

Les articles et les présentations générales constituent un style rédactionnel particulièrement adapté pour fournir un résumé détaillé d’un sujet ou d’un concept. Ils peuvent présenter une technologie ou expliquer comment un concept peut être appliqué, sans pour autant aborder les étapes précises de manière trop détaillée. Cependant, ce type de contenu peut servir de point d’entrée aux lecteurs pour trouver des ressources pédagogiques et de référence qui le font, telles que des tutoriels, des exemples et la documentation des classes. Un exemple de présentation générale pourrait être une page 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, 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 « Commandes de rédaction » répertorie les arguments disponibles pour la commande ` \page `.

Exemples de code

Les exemples constituent un moyen efficace de démontrer l'utilisation pratique d'une technologie ou d'un concept donné. En matière de middleware, cela prend généralement la forme d'une application utilisant un code simple et accompagnée d'explications claires sur le fonctionnement de ce code. Tout module, API, projet, modèle, etc. devrait disposer d'au moins un bon exemple.

Un exemple peut s’accompagner d’un tutoriel. Le tutoriel explique et décrit le code, tandis que l’exemple de code correspond au contenu que les utilisateurs peuvent étudier. Les exemples de code peuvent comporter du texte d’accompagnement qui ne figure pas dans le tutoriel.

QDoc créera une page contenant l’exemple de code ainsi qu’une description à l’aide de la \example commande.

/*!
    \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 d’entrée `exampledirs ` pour trouver le fichier Qt Project (.pro) afin de générer les fichiers d’exemple. Le fichier HTML généré portera le nom ` declarative-ui-components-tabwidget.html`. QDoc répertoriera également l’ensemble du code d’exemple.