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 se trouver dans les fichiers d'implémentation tels que .cpp.

Documentation des classes

La documentation d'une classe est générée à l'aide de la commande \class 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
*/

Lescommandes contextuelles ajoutent des informations sur la classe, telles que son module ou la version dans laquelle la classe a été ajoutée.

Les commandes contextuelles les plus courantes sont les suivantes

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

Description brève et détaillée

La description brève est marquée par la commande \brief et sert à résumer l'objectif ou la fonctionnalité de la classe. Pour les classes C++, QDoc prend la classe et crée des informations annotées pour la classe. Les informations annotées apparaissent dans les listes et les tableaux qui affichent la classe.

La description de la classe C++ doit commencer par :

"The <C++ class name> class"

La section de description détaillée commence après la brève description. 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 brève et la description détaillée.

Fonctions membres

En règle générale, la documentation relative aux fonctions précède immédiatement l'implémentation de la fonction dans le fichier .cpp. Pour la documentation d'une fonction qui n'est pas immédiatement au-dessus de l'implémentation, l'élément \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 de la 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 dans la documentation des fonctions

• "Construit..." - pour les constructeurs
• "Détruit..." - pour les destructeurs
• "Retourne..." - pour les fonctions d'accès

La documentation de la fonction doit documenter

• le type de retour
• les paramètres
• les actions des fonctions

La commande \a marque le paramètre dans la documentation. La documentation du type de retour doit être liée à la documentation du type ou être marquée par la commande \c dans le cas de 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 sur les propriétés se trouve immédiatement au-dessus de l'implémentation de la fonction read. 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 sur les propriétés commence généralement par "Cette propriété...", mais il s'agit d'expressions alternatives :

• "Cette propriété détient..."
• "Cette propriété décrit...
• "Cette propriété représente...
• "Renvoie true lorsque... et false lorsque..." - pour les propriétés qui sont lues.
• "Sets the..." - pour les propriétés qui configurent un type.

La documentation sur les propriétés doit inclure

• la 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 maximum). Par défaut, la propriété est définie sur 0.0 (pas de flou).

Signaux, notificateurs et emplacements

La commande topic pour les signaux, les notificateurs et les slots est la suivante \fn. La documentation sur les signaux indique 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 des 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..."
• "Cet emplacement est exécuté lorsque..."

Pour les propriétés qui ont 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 faire référence à la propriété et de mentionner 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.
*/

Enums, espaces de noms et autres types

Les Enums, les espaces de noms et les macros disposent d'une commande topic pour leur documentation :

• \enum
• \typedef
• \macro

Le style de langage pour ces types mentionne qu'il s'agit d'une énumération ou d'une macro et continue avec la description du type.

Pour les énumérations, la commande \value permet de dresser la liste des valeurs. QDoc crée un tableau de 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.
*/