Style de documentation C++

Pour générer la documentation, QDoc parcourt le code source et génère de la documentation pour les types C++ tels que les classes. QDoc associe ensuite les fonctions membres, les propriétés et les autres types à la classe appropriée.

Notez que la documentation doit figurer dans les fichiers d’implémentation, tels que .cpp.

Documentation des classes

La documentation des classes est générée à l’aide de la \class commande et le nom de la classe comme premier argument.

/*!
    \class QCache
    \brief The QCache class is a template class that provides a cache.

    \ingroup tools
    \ingroup shared

    \reentrant

    QCache\<Key, T\> defines a cache that stores objects of type T
    associated with keys of type Key. For example, here's the
    definition of a cache that stores objects of type Employee
    associated with an integer key:

    \snippet code/doc_src_qcache.cpp 0

    Here's how to insert an object in the cache:

    \snippet code/doc_src_qcache.cpp 1

    ... detailed description omitted

    \sa QPixmapCache, QHash, QMap
*/

Les commandes de contexte ajoutent des informations sur la classe, telles que son module ou la version dans laquelle elle a été ajoutée.

Voici quelques commandes de contexte courantes :

• \brief - la brève description de la classe (obligatoire)
• \since - la version dans laquelle la classe a été ajoutée (obligatoire)
• \internal - marque la classe comme interne. Les classes internes n'apparaissent pas dans la documentation de l'API publique.

La description succincte et la description détaillée

La description succincte est indiquée par la \brief et sert à résumer l'objectif ou la fonctionnalité de la classe. Pour les classes C++, QDoc récupère la classe et génère des informations annotées la concernant. Ces informations annotées apparaissent dans des listes et des tableaux présentant la classe.

La description succincte en C++ doit commencer par :

"The <C++ class name> class"

La section de description détaillée commence après la description succincte. Elle fournit davantage d’informations sur la classe. La description détaillée peut contenir des images, des extraits de code ou des liens vers d’autres documents pertinents. Une ligne vide doit séparer la description succincte de la description détaillée.

Fonctions membres

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 .cpp. Pour la documentation d’une fonction qui ne se trouve pas immédiatement au-dessus de l’implémentation, le tag \fn est nécessaire.

/*!
  \fn QString &QString::remove(int position, int n)

  Removes \a n characters from the string, starting at the given \a
  position index, and returns a reference to the string.

  If the specified \a position index is within the string, but \a
  position + \a n is beyond the end of the string, the string is
  truncated at the specified \a position.

  \snippet qstring/main.cpp 37

  \sa insert(), replace()
*/
QString &QString::remove(int pos, int len)

La documentation d’une fonction commence par un verbe, indiquant l’opération effectuée par la fonction. Cela s’applique également aux constructeurs et aux destructeurs.

Voici quelques verbes courants utilisés dans la documentation des fonctions :

• « Construit... » - pour les constructeurs
• « Détruit… » – pour les destructeurs
• « Renvoie... » – pour les fonctions d'accès

La documentation d'une 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 comporter un lien vers la documentation du type ou être mise en évidence à l’aide de la \c commande dans le cas des valeurs booléennes.

/*!
    Returns \c true if a QScroller object was already created for \a target; \c false otherwise.

    \sa scroller()
*/
bool QScroller::hasScroller(QObject *target)

Propriétés

La documentation relative aux propriétés se trouve immédiatement au-dessus de l’implémentation de la fonction de lecture. La commande « topic » pour les propriétés est \property.

/*!
    \property QVariantAnimation::duration
    \brief the duration of the animation

    This property describes the duration in milliseconds of the
    animation. The default duration is 250 milliseconds.

    \sa QAbstractAnimation::duration()
 */
int QVariantAnimation::duration() const

La documentation relative aux propriétés commence généralement par « Cette propriété... », mais il existe d’autres formulations possibles :

• « 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 en lecture.
• « Définit le... » – pour les propriétés qui configurent un type.

La documentation d’une propriété doit inclure :

• une description et le comportement de la propriété
• les valeurs acceptées pour la propriété
• la valeur par défaut de la propriété

Comme pour les fonctions, le type par défaut peut être lié ou marqué à l'aide de la commande ` \c `.

Voici un exemple de style de plage de valeurs :

Les valeurs vont de 0,0 (pas de flou) à maximumRadius (flou maximal). Par défaut, la propriété est définie sur 0,0 (pas de flou).

Signaux, notificateurs et slots

La commande de rubrique pour les signaux, les notificateurs et les slots est \fn. La documentation des signaux précise quand ils sont déclenchés ou émis.

/*!
  \fn QAbstractTransition::triggered()

  This signal is emitted when the transition has been triggered (after
  onTransition() has been called).
*/

La documentation relative aux signaux commence généralement par « Ce signal est déclenché lorsque… ». Voici d’autres styles possibles :

• « Ce signal est déclenché lorsque… »
• « Déclenché lorsque… »
• « Émis lorsque… »

Pour les slots ou les notificateurs, la condition dans laquelle ils sont exécutés ou déclenchés par un signal doit être documentée.

• « Exécuté lorsque… »
• « Ce slot est exécuté lorsque… »

Pour les propriétés comportant des signaux surchargés, QDoc regroupe les notificateurs surchargés. Pour faire référence à une version spécifique d’un notificateur ou d’un signal, il suffit de mentionner la propriété et d’indiquer qu’il existe différentes versions du notificateur.

/*!
\property QSpinBox::value
\brief the value of the spin box

setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/

Énumérations, espaces de noms et autres types

Les énumérations, les espaces de noms et les macros disposent d'une commande de rubrique pour leur documentation :

• \enum
• \typedef
• \macro

Le style de description de ces types précise qu'il s'agit d'une énumération ou d'une macro, puis se poursuit par la description du type.

Pour les énumérations, la \value commande sert à lister les valeurs. QDoc crée un tableau des valeurs pour l’énumération.

/*!
    \enum QSql::TableType

    This enum type describes types of SQL tables.

    \value Tables  All the tables visible to the user.
    \value SystemTables  Internal tables used by the database.
    \value Views  All the views visible to the user.
    \value AllTables  All of the above.
*/