Statut

Ces commandes permettent d'indiquer qu'un élément documenté a un statut particulier. L'élément peut être marqué comme déprécié, c'est-à-dire qu'il est sur le point d'être rendu obsolète et n'est plus inclus dans l'interface publique. La commande \since permet de spécifier le numéro de version dans lequel une fonction ou une classe est apparue pour la première fois. La commande \qmlabstract permet de marquer un type QML comme une classe de base abstraite.

\abstract et \qmlabstract

\abstractest un synonyme de la commande \qmlabstract. Ajoutez cette commande au commentaire d'un type QML lorsque ce type est destiné à être utilisé uniquement comme un type de base abstrait. \qmltype d'un type QML lorsque ce type est destiné à être utilisé uniquement comme un type de base abstrait. Lorsqu'un type QML est abstrait, cela signifie qu'il ne peut pas être instancié. Au lieu de cela, les propriétés de son API publique sont incluses dans la liste des propriétés publiques de la page de référence de chaque type QML qui hérite du type QML abstrait. Les propriétés sont documentées comme s'il s'agissait de propriétés du type QML héritant.

Normalement, lorsqu'un type QML est marqué d'un astérisque \qmlabstractil est également marqué par \internal afin que sa page de référence ne soit pas générée. Si le type QML abstrait n'est pas marqué interne, il aura une page de référence dans la documentation.

\attribution

La commande \attribution marque un document \page comme documentation d'attribution de licence.

La commande \generatelist annotatedattributions génère une liste annotée de toutes les pages d'attribution de licence dans le projet de documentation.

\default

La commande \default est utilisée pour documenter une valeur par défaut pour une propriété QML. La commande prend un seul argument, qui est affiché dans la documentation comme valeur par défaut.

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

Si la valeur par défaut est une chaîne non vide, utilisez des guillemets :

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

Utilisez la commande \compares pour décrire les résultats de la comparaison du type C++ documenté avec lui-même. Vous devez utiliser cette commande en conjonction avec la commande \class avec la commande

\compares prend l'un des arguments suivants :

• strong
• partial
• weak
• equality

strong, partial, et weak se rapportent à l'ordre. equality signifie que le type n'est comparé que pour l'égalité.

Cette commande a été introduite dans QDoc avec Qt 6.7.

Voir aussi \compareswith.

\compareswith

Utilisez la paire de commandes \compareswith .. \endcompareswith pour décrire les résultats de la comparaison du type C++ documenté par rapport à d'autres types. \compareswith prend deux arguments ou plus : une catégorie de comparaison, suivie d'un nom de type, ou une liste de noms de types séparés par des espaces. Toutes les lignes de texte entre les commandes \compareswith et \endcompareswith sont considérées comme des détails supplémentaires qui s'appliquent à tous les types soumis à l'argument de la catégorie de comparaison.

Les types dont le nom comporte un ou plusieurs espaces, comme unsigned long, doivent être placés entre accolades.

Par exemple :

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

Les arguments placés entre accolades sont dépourvus d'espaces blancs en début et en fin de phrase. Par exemple, unsigned long et unsigned long sont équivalents.

L'argument de la catégorie de comparaison doit être l'un des suivants :

• strong
• partial
• weak
• equality

strong, partial, et weak se rapportent à l'ordre. equality signifie que le type n'est comparé que pour l'égalité.

Cette commande a été introduite dans QDoc avec Qt 6.7.

Voir aussi \compares.

\qmldefault

La commande \qmldefault permet de marquer une propriété QML comme propriété par défaut. Le mot default est affiché dans la documentation de la propriété.

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

Voir comment QDoc rend cette propriété sur la page de référence du type State.

\qmlenumeratorsfrom

Utilisez la commande \qmlenumeratorsfrom dans une rubrique \qmlproperty avec une propriété de type énumération, pour reproduire automatiquement la documentation sur les énumérateurs d'une rubrique C++. \enum C++.

La commande prend en argument une énumération C++ entièrement qualifiée et génère une liste d'énumérateurs et leurs descriptions.

Par défaut, chaque énumérateur est préfixé par le nom du type auquel la propriété appartient, avec . comme séparateur.

Par exemple, l'énumérateur est préfixé par le nom du type auquel la propriété appartient :

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

Si les énumérateurs sont enregistrés dans QML sous un nom de type différent, ce nom (préfixe) peut être spécifié en utilisant l'argument optionnel entre crochets :

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

Cette commande a été introduite dans QDoc 6.8.

Voir aussi \qmlproperty, \enum, et \value.

\dontdocument

La commande \dontdocument n'est utilisée que dans un fichier dontdocument.qdoc pour un module particulier. Ce fichier spécifie les classes ou les structures déclarées publiquement qui ne sont pas destinées à être documentées. QDoc n'affichera pas d'avertissement concernant l'absence de commentaires \class pour ces classes et ces structures.

Vous trouverez ci-dessous la commande \dontdocument dans le fichier dontdocument.qdoc pour les widgets :

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

La méta-commande \inheaderfile est utilisée pour remplacer l'instruction include générée pour la documentation de référence d'une classe C++, d'un espace de noms ou d'un fichier d'en-tête.

Par défaut, QDoc documente un site \class SomeClass pour qu'il soit disponible avec l'instruction include suivante :

#include <SomeClass>

Si l'instruction d'inclusion réelle diffère de l'instruction par défaut, elle peut être documentée comme suit

\class SomeClass
\inheaderfile Tools/SomeClass
...

Voir aussi \class et \headerfile.

\obsolete

La commande \obsolete est remplacée par la commande \deprecated.

Cette commande n'est conservée que pour des raisons de compatibilité ascendante. Elle pourrait être supprimée dans une prochaine version de QDoc. Utilisez la commande \deprecated à la place.

Voir aussi \deprecated.

\deprecated

La commande \deprecated permet d'indiquer que l'élément associé est obsolète et qu'il ne doit plus être utilisé dans le nouveau code.

La commande \deprecated prend deux arguments facultatifs :

• Une version entre crochets (par exemple [6.2]).
• Une chaîne de caractères contenant plus d'informations, par exemple une suggestion de remplacement.

Lors de la génération de la documentation de référence d'une classe, QDoc crée une page séparée qui documente les membres obsolètes. C'est une bonne pratique de suggérer une alternative équivalente.

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\internal

La commande \internal indique que l'élément documenté ne fait pas partie de l'interface publique.

La commande doit figurer sur sa propre ligne.

QDoc ignore la documentation ainsi que l'élément documenté lorsqu'il génère la documentation de référence de la classe associée.

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

Cette fonction ne sera pas incluse dans la documentation, sauf si QDoc est appelé avec l'option de ligne de commande -showinternal ou si la variable d'environnement QDOC_SHOW_INTERNAL est définie.

\modulestate

Utilisez la commande \modulestate dans une rubrique \module ou \qmlmodule pour fournir une description personnalisée de l'état du module.

La commande prend un argument qui décrit l'état du module. Par exemple, la commande

/*!
    \module QtFoo
    \modulestate Experimental
*/

QDoc ajoutera cette information sur la page du module :

Ce module est à l'état expérimental.

Dans la sortie HTML, ces informations sur l'état apparaissent également dans la barre de navigation (breadcrumbs) des pages de référence pour les membres du module.

Voir aussi \preliminary.

\preliminary

La commande \preliminary permet d'indiquer que l'élément documenté est encore en cours de développement.

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

La commande \preliminary renvoie à une notification dans la documentation et indique que l'élément est préliminaire lorsqu'il apparaît dans des listes.

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

\readonly

La commande \readonly est utilisée en conjonction avec une commande \qmlproperty pour marquer la propriété QML comme étant en lecture seule.

\required

La commande \required est utilisée en conjonction avec une commande \qmlproperty pour marquer la propriété QML comme requise.

Voir aussi Le système de propriété.

\since

La commande \since indique dans quelle version mineure la fonctionnalité associée a été ajoutée.

Si l'argument transmis à \since ne contient pas d'espaces, il est considéré comme une notation abrégée du nom du produit et QDoc préfixe la version avec la valeur de productname dans la sortie générée. Si la variable productname est indéfinie, QDoc ne génère que la chaîne de la version.

L'argument peut également contenir explicitement le nom du produit :

\since MyFramework 2.0

Dans ce cas, les arguments (produit et version) sont utilisés tels quels.

Héritage des informations Since

Depuis la version 6.5 de QDoc, les classes C++ et les types QML héritent de la déclaration \since de leur module ou module QML respectif, sauf si \since est explicitement utilisé dans la documentation du type.

Clause Since

La commande \value permet à une clause optionnelle since, entre crochets, de suivre immédiatement la chaîne de commande. Elle est utilisée pour marquer des valeurs d'énumération C++ spécifiques avec des informations "since".

Voir aussi \value et ignoresince.

\wrapper

La commande \wrapper, lorsqu'elle est utilisée dans la documentation d'une classe C++, marque la classe comme un wrapper qui fournit un accès à une API non Qt. Cette commande est utilisée pour supprimer les avertissements qui pourraient être générés pour les membres d'une telle classe.