Introduction à QDoc

QDoc est un outil utilisé par les développeurs de Qt pour générer de la documentation pour les projets de logiciels. Il fonctionne en extrayant les commentaires QDoc des fichiers source du projet et en formatant ensuite ces commentaires sous forme de pages HTML ou de documents DocBook XML. QDoc trouve 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, un commentaire QDoc commence toujours par un point d'exclamation ( !):

/*!
    \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 bonne documentation dans vos fichiers source. Il explique également comment créer un fichier de configuration QDoc, que vous transmettrez à QDoc sur la ligne de commande.

Exécution de QDoc

Le nom du programme QDoc est qdoc. Pour exécuter QDoc à partir de la ligne de commande, donnez-lui le nom d'un fichier de configuration :

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

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

Voir Le fichier de configuration de QDoc pour savoir comment mettre en place un fichier de configuration de QDoc.

Fonctionnement de QDoc

QDoc commence par lire le fichier de configuration que vous avez spécifié sur la ligne de commande. Il enregistre toutes les variables du fichier de configuration en vue d'une utilisation ultérieure. L'une des premières variables utilisées est outputformats. Cette variable indique à QDoc les générateurs de sortie qu'il doit exécuter. La valeur par défaut est HTML, donc 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 voulez de toute façon, mais vous pouvez aussi spécifier DocBook pour obtenir une sortie DocBook à la place.

Ensuite, QDoc utilise les valeurs de la variable headerdirs et/ou de la variable headers pour trouver et analyser tous les fichiers d'en-tête de votre projet. QDoc n' analyse pas les fichiers d'en-tête à la recherche de commentaires QDoc. Il analyse les fichiers d'en-tête pour construire un arbre principal de tous les éléments qui devraient être documentés, en d'autres termes, les éléments pour lesquels QDoc devrait trouver des commentaires QDoc.

Après avoir analysé tous les fichiers d'en-tête et construit l'arbre principal des éléments à documenter, QDoc utilise la valeur de la variable sourcedirs et/ou la valeur de la variable sources pour trouver et analyser tous les fichiers .cpp et .qdoc de votre projet. C'est dans ces fichiers que QDoc recherche les commentaires QDoc. Rappelez-vous qu'un commentaire QDoc commence par un point d'exclamation : /* !.

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

Enfin, QDoc parcourt l'arbre principal. Pour chaque nœud, si le nœud a stocké de la documentation, QDoc appelle le générateur de sortie spécifié par la variable outputformats pour formater et écrire la documentation dans le répertoire spécifié dans le fichier de configuration dans la variable outputdir.

Types de commandes

QDoc interprète trois types de commandes :

• Commandes de sujet
• Commandes de contexte
• Commandes de balisage

Les commandes de sujet identifient l'élément que vous documentez, par exemple une classe C++, une fonction, un type ou une page de texte supplémentaire qui ne correspond pas à un é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 les pages suivantes et précédentes, 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 rendus, ou la structure du document.