Relier les choses

Les commandes de mise en relation permettent de spécifier comment un élément documenté est lié à un autre élément documenté. 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 de documenter le fait qu'un type QML hérite d'un autre type QML.

Commandes

\inherits

La commande \inherits permet de documenter le fait qu'un type QML hérite d'un autre type QML. Elle doit être incluse dans le commentaire de l'élément héritant. \qmltype de l'élément héritant. L'argument est le nom du type QML hérité, éventuellement qualifié par un nom de 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 Animation

Lorsque l'on documente un type QML directement dans un fichier .qml, la commande \inherits n'est normalement pas nécessaire car QDoc peut détecter le type de base à partir de la syntaxe QML. Si elle est présente, la commande \inherits annulera cette détection automatique du type de base.

\overload

Utilisez la commande \overload pour marquer les surcharges de fonctions C++. Cette commande doit apparaître sur sa propre ligne dans le commentaire de la documentation.

Fonctionnement

Lorsque vous avez plusieurs fonctions C++ portant le même nom (surcharges) qui effectuent un travail similaire avec des paramètres différents, utilisez la commande \overload pour éviter une documentation répétitive. 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 par \overload suppriment automatiquement les avertissements relatifs aux paramètres manquants, puisqu'elles font référence à la documentation de la fonction principale.

Utilisation de base

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

Lien vers la fonction principale

Ajouter le nom de la fonction pour créer un lien vers la fonction primaire :

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

Utilisez des noms qualifiés (ClassName::functionName()) ou 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 primaire

Par défaut, QDoc choisit automatiquement la surcharge primaire. Pour désigner explicitement la surcharge primaire, utilisez :

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

Surcharges primaires :

• contiennent la documentation de la fonction principale
• Exigent une documentation complète des paramètres.
• Ne pas afficher le texte "Cette fonction surcharge...".
• Servent de cible de lien pour les autres surcharges.

Utilisez \overload primary 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 permet d'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 permet de s'assurer qu'une fonction non documentée sera incluse.

La commande doit être placée sur sa propre ligne.

/*!
    \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é (fonction, macro, typedef, enum ou 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 de l'en-tête auquel l'entité est liée.

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

/*!
    \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 de cette fonction est incluse dans la page de référence de la classe QChar, listée dans la section Related Non-members.