Introduction à QDoc

QDoc est un outil utilisé par les développeurs Qt pour générer de la documentation pour des projets logiciels. Il fonctionne en extrayant les commentaires QDoc des fichiers source du projet, puis en les mettant en forme sous forme de pages HTML ou de documents XML DocBook. QDoc recherche les commentaires QDoc dans les fichiers « .cpp » et « .qdoc ». QDoc ne recherche pas les commentaires QDoc dans les fichiers « .h ». Un commentaire QDoc commence toujours par un point d’exclamation (!). Par exemple :

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

À partir du commentaire QDoc ci-dessus, QDoc génère la page HTML QObject class reference.

Ce manuel explique comment utiliser les commandes QDoc dans les commentaires QDoc pour intégrer une documentation de qualité dans vos fichiers source. Il explique également comment créer un fichier de configuration QDoc, que vous passerez à QDoc depuis la ligne de commande.

Exécution de QDoc

Le nom du programme QDoc est qdoc. Pour exécuter QDoc depuis la ligne de commande, indiquez-lui le nom d’un fichier de configuration :

$ ../../bin/qdoc ./config.qdocconf

QDoc reconnaît l'extension .qdocconf comme un fichier de configuration QDoc. C'est dans ce fichier de configuration que vous indiquez à QDoc où trouver les fichiers source du projet, les fichiers d'en-tête et les fichiers d'.qdoc. C'est également là que vous indiquez à QDoc quel type de sortie générer (HTML, DocBook XML…) et où placer la documentation générée. Le fichier de configuration contient également d’autres informations destinées à QDoc.

Consultez la section « Le fichier de configuration de QDoc » pour savoir comment configurer un fichier de configuration QDoc.

Fonctionnement de QDoc

QDoc commence par lire le fichier de configuration que vous avez spécifié sur la ligne de commande. Il stocke toutes les variables du fichier de configuration en vue d’une utilisation ultérieure. L'une des premières variables qu'il utilise est « outputformats ». Cette variable indique à QDoc quels générateurs de sortie il doit exécuter. La valeur par défaut est « HTML »; ainsi, si vous ne définissez pas « outputformats » dans votre fichier de configuration, QDoc générera une sortie HTML. C'est généralement ce que vous souhaiterez de toute façon, mais vous pouvez également spécifier « DocBook » pour obtenir une sortie DocBook à la place.

Ensuite, QDoc utilise les valeurs des variables ` headerdirs ` et/ou ` headers ` pour rechercher et analyser tous les fichiers d'en-tête de votre projet. QDoc ne recherche pas les commentaires QDoc dans les fichiers d’en-tête. Il analyse ces fichiers afin de construire une arborescence principale regroupant tous les éléments devant être documentés, c’est-à-dire les éléments pour lesquels QDoc doit rechercher des commentaires QDoc.

Après avoir analysé tous les fichiers d’en-tête et construit l’arborescence principale des éléments à documenter, QDoc utilise la valeur de la variable `sourcedirs` et/ou celle de la variable `sources` pour rechercher et analyser tous les fichiers ` .cpp ` et ` .qdoc ` de votre projet. Ce sont ces fichiers que QDoc analyse à la recherche de commentaires QDoc. N’oubliez pas qu’un commentaire QDoc commence par un point d’exclamation : /*!.

Pour chaque commentaire QDoc qu’il trouve, il recherche dans l’arborescence principale l’élément auquel appartient la documentation. Il interprète ensuite les commandes QDoc contenues dans le commentaire et stocke les commandes interprétées ainsi que le texte du commentaire dans le nœud de l’arborescence correspondant à cet élément.

Enfin, QDoc parcourt l’arborescence principale. Pour chaque nœud, si celui-ci contient de la documentation, QDoc appelle le générateur de sortie spécifié par la variable ` outputformats ` afin de formater et d’écrire la documentation dans le répertoire indiqué dans le fichier de configuration au niveau de la variable `outputdir`.

Types de commandes

QDoc interprète trois types de commandes :

• Commandes de rubrique
• Commandes de contexte
• Commandes de balisage

Les commandes de rubrique identifient l'élément que vous documentez, par exemple une classe, une fonction ou un type C++, ou encore une page de texte supplémentaire qui ne correspond à aucun élément C++ sous-jacent.

Les commandes de contexte indiquent à QDoc comment l’élément documenté est lié à d’autres éléments documentés, par exemple les liens vers la page suivante et la page précédente, l’inclusion dans des groupes de pages ou des modules de bibliothèque. Les commandes de contexte peuvent également fournir des informations sur l’élément documenté que QDoc ne peut pas obtenir à partir des fichiers source, par exemple si l’élément est thread-safe, s’il s’agit d’une fonction surchargée ou réimplémentée, ou s’il a été déprécié.

Les commandes de balisage indiquent à QDoc comment les éléments de texte et d’image du document doivent être affichés, ou fournissent des informations sur la structure du plan du document.