Mettre des éléments en relation

Les commandes de relation permettent de préciser comment un élément documenté est lié à un autre élément documenté. Voici quelques exemples :

• Cette fonction est une surcharge d'une autre fonction.
• Cette fonction est une réimplémentation d'une autre fonction.
• Ce `typedef` est lié à une classe ou à un fichier d'en-tête.

Il existe également une commande permettant d'indiquer qu'un type QML hérite d'un autre type QML.

Commandes

\inherits

La commande \inherits permet d’indiquer qu’un type QML hérite d’un autre type QML. Elle doit être incluse dans la balise \qmltype . L’argument est le nom du type QML dont il hérite, éventuellement suivi du nom d’un module QML.

/*!
    \qmltype PauseAnimation
    \inqmlmodule QtQuick
    \nativetype QDeclarativePauseAnimation
    \ingroup qml-animation-transition
    \since 4.7
    \inherits Animation
    \brief The PauseAnimation element provides a pause for an animation.

    When used in a SequentialAnimation, PauseAnimation is a step
    when nothing happens, for a specified duration.

    A 500ms animation sequence, with a 100ms pause between two animations:

    SequentialAnimation {
        NumberAnimation { ... duration: 200 }
        PauseAnimation { duration: 100 }
        NumberAnimation { ... duration: 200 }
    }

    \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
*/

QDoc inclut cette ligne dans la page de référence de l'élément PauseAnimation:

Hérite de Animation

Lors de la documentation d'un type QML directement dans un fichier .qml, la commande ` \inherits ` n'est généralement pas nécessaire, car QDoc peut détecter le type de base à partir de la syntaxe QML. Si elle est présente, une commande ` \inherits ` remplacera cette détection automatique du type de base.

\overload

Utilisez la \overload commande pour marquer les surcharges de fonctions C++. Cette commande doit figurer sur une ligne distincte dans le commentaire de documentation.

Fonctionnement

Lorsque vous disposez de plusieurs fonctions C++ portant le même nom (surcharges) qui effectuent des tâches similaires avec des paramètres différents, utilisez \overload pour éviter les répétitions dans la documentation. Les fonctions sans \overload nécessitent une documentation complète. Les fonctions avec \overload peuvent se concentrer sur leurs différences spécifiques.

Les fonctions marquées avec \overload suppriment automatiquement les avertissements relatifs aux paramètres manquants, puisqu’elles renvoient à la documentation de la fonction principale.

Utilisation de base

/*!
    \overload
    Brief description of what makes this overload different.
*/

Liaison à la fonction principale

Ajoutez le nom de la fonction pour créer un lien vers la fonction principale :

/*!
    \overload functionName()
    Brief description of what makes this overload different.
*/

Utilisez soit des noms qualifiés (ClassName::functionName()), soit des noms non qualifiés (functionName()). QDoc qualifie automatiquement les noms non qualifiés en utilisant la classe ou l'espace de noms actuel.

Désignation d’une surcharge principale

Par défaut, QDoc choisit automatiquement la surcharge principale. Pour désigner explicitement quelle surcharge doit servir de surcharge principale, utilisez :

/*!
    \overload primary
    Main documentation for this function family.
    Document all parameters here.
*/

Surcharges principales :

• Contiennent la documentation de la fonction principale.
• Une documentation complète des paramètres est requise.
• Ne pas afficher le texte « Cette fonction surcharge… ».
• Servent de cible de lien pour les autres surcharges.

Utilisez principalement `\overload ` lorsque la surcharge la plus importante diffère de la sélection automatique de QDoc, ou lorsque vous avez besoin d’un comportement de liaison cohérent.

\reimp

La commande \reimp sert à indiquer qu’une fonction est une réimplémentation d’une fonction virtuelle sans nécessiter de documentation supplémentaire.

Par défaut, QDoc omettra une fonction virtuelle réimplémentée de la référence de classe, à moins qu'elle ne soit documentée. Cette commande garantit qu'une fonction qui, sans cela, ne serait pas documentée, sera incluse.

La commande doit figurer sur une ligne distincte.

/*!
    \reimp
*/
void QToolButton::nextCheckState()
{
    Q_D(QToolButton);
    if (!d->defaultAction)
        QAbstractButton::nextCheckState();
    else
        d->defaultAction->trigger();
}

Cette fonction ne sera pas incluse dans la documentation. À la place, un lien vers la fonction de base QAbstractButton::nextCheckState() apparaîtra dans la documentation.

\relates

La commande \relates permet d'inclure la documentation d'une entité (une fonction, une macro, un typedef, une énumération ou une variable) dans une classe, un espace de noms ou un fichier d'en-tête. L'argument est le nom de la classe, de l'espace de noms ou du fichier d'en-tête auquel l'entité est associée.

Si l’argument fait référence à un type modélisé, utilisez uniquement le nom du type (sans les paramètres de modèle).

/*!
    \relates QChar

    Reads a char from the stream \a in into char \a chr.

    \sa {Format of the QDataStream operators}
*/
QDataStream &operator>>(QDataStream &in, QChar &chr)
{
    quint16 u;
    in >> u;
    chr.unicode() = ushort(u);
    return in;
}

La documentation relative à cette fonction figure sur la page de référence de la classe ` QChar`, dans la section « Éléments non membres associés ».