Statut

Ces commandes servent à indiquer qu’un élément documenté présente un statut particulier. L’élément peut être marqué comme « obsolète », c’est-à-dire qu’il est sur le point d’être supprimé et ne figurera plus dans l’interface publique. La \since commande permet de préciser le numéro de version dans laquelle une fonction ou une classe est apparue pour la première fois. La \qmlabstract commande sert à marquer un type QML comme classe de base abstraite.

\abstract et \qmlabstract

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

Normalement, lorsqu’un type QML est marqué avec \qmlabstract, il est également marqué avec \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é comme « interne », il disposera d’une page de référence dans la documentation.

\attribution

La commande « \attribution » marque une licence documentée \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 du projet de documentation.

\default

La commande ` \default ` sert à documenter la valeur par défaut d’une propriété QML. Elle prend un seul argument, qui s’affiche dans la documentation en tant que valeur par défaut.

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

Si la valeur par défaut est une chaîne de caractères 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é lorsqu’il est comparé à lui-même. Vous devez utiliser cette commande en conjonction avec la \class commande.

\compares prend l’un des arguments suivants :

• strong
• partial
• weak
• equality

strong, « partial » et « weak » concernent l’ordre de comparaison. « equality » signifie que le type est uniquement comparé pour vérifier 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. La commande \compareswith prend deux arguments ou plus : une catégorie de comparaison, suivie d’un nom de type ou d’une liste de noms de types séparés par des espaces. Toutes les lignes de texte situées entre les commandes \compareswith et \endcompareswith sont considérées comme des détails supplémentaires s’appliquant à tous les types concernés par l’argument de catégorie de comparaison.

Les types dont le nom comporte un ou plusieurs espaces, tels que 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 voient leurs espaces blancs de début et de fin supprimés. Par exemple, unsigned long et unsigned long sont équivalents.

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

• strong
• partial
• weak
• equality

strong, partial et weak concernent l’ordre de tri. equality signifie que les types sont uniquement comparés pour vérifier s’ils sont égaux.

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

Voir aussi \compares.

\qmldefault

La commande « \qmldefault » permet de désigner une propriété QML comme propriété par défaut. Le terme « default » apparaît 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.
*/

Découvrez comment QDoc présente cette propriété sur la page de référence du type « State ».

\qmlenumeratorsfrom

Utilisez la commande ` \qmlenumeratorsfrom ` dans un \qmlproperty rubrique comportant une énumération de types de propriétés, pour reproduire automatiquement la documentation des éléments d'énumération à partir d'un \enum .

La commande prend comme argument une énumération C++ entièrement qualifiée et génère une liste des éléments de l'énumération ainsi que leurs descriptions.

Par défaut, chaque élément de l'énumération est préfixé par le nom du type auquel appartient la propriété, avec « . » comme séparateur.

Par exemple :

/*!
    \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é à l'aide de l'argument facultatif 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` propre à un module donné. Ce fichier spécifie les classes ou structures déclarées publiquement qui ne doivent pas être documentées. QDoc n’affichera pas d’avertissements concernant l’absence de commentaires d’ \class s pour ces classes et structures.

Vous trouverez ci-dessous la commande ` \dontdocument ` dans le fichier `dontdocument.qdoc` dédié aux widgets :

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

La méta-commande « \inheaderfile » permet de remplacer l'instruction d'inclusion 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 une directive ` \class SomeClass ` comme étant disponible via la directive d'inclusion suivante :

#include <SomeClass>

Si la directive d'inclusion réelle diffère de celle 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 est conservée uniquement pour des raisons de compatibilité ascendante. Elle pourrait être supprimée dans une future version de QDoc. Utilisez plutôt la commande \deprecated.

Voir aussi \deprecated.

\deprecated

La commande « \deprecated » sert à 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 des informations supplémentaires, par exemple une alternative suggérée.

Lors de la génération de la documentation de référence d'une classe, QDoc crée une page distincte répertoriant les membres obsolètes et y ajoute un lien. Il est recommandé de proposer 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 une ligne distincte.

QDoc ignore la documentation ainsi que l'élément documenté lors de la génération de la documentation de référence associée à la classe.

/*!
    \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, à moins que QDoc ne soit appelé avec l’option de ligne de commande « -showinternal » ou que la variable d’environnement « QDOC_SHOW_INTERNAL » soit définie.

\modulestate

Utilisez la commande ` \modulestate ` dans une rubrique de type ` \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 :

/*!
    \module QtFoo
    \modulestate Experimental
*/

QDoc ajoutera alors ces informations sur la page du module :

Ce module est en état « Expérimental ».

Dans la sortie HTML, cette information relative au statut apparaît également dans la barre de navigation (fil d'Ariane) des pages de référence des membres du module.

Voir aussi \preliminary.

\preliminary

La commande « \preliminary » sert à indiquer que l'élément documenté est encore en cours de développement.

Cette commande doit figurer sur une ligne distincte.

La commande \preliminary génère une note dans la documentation et marque l’élément comme « 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);
}

Depuis la version 6.12 de QDoc, il est possible de personnaliser le descripteur d’état et le contenu de la note générée pour les éléments marqués avec \preliminary.

Voir également preliminary la variable de configuration.

\readonly

La commande « \readonly » s’utilise conjointement avec une \qmlproperty commande pour marquer la propriété QML comme étant en lecture seule.

\required

La commande « \required » s'utilise conjointement avec une \qmlproperty commande pour marquer la propriété QML comme obligatoire.

Voir également « Le système de propriétés ».

\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 ajoutera en préfixe à la version la valeur de productname dans la sortie générée. Si la variable productname n'est pas définie, QDoc génère uniquement la chaîne de 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, à moins que ` \since ` ne soit explicitement utilisé dans la documentation du type.

Clause « Since »

La commande ` \value ` permet d'ajouter une clause `since` facultative, placée entre crochets, immédiatement après la chaîne de commande. Elle sert à associer des informations `since` à des valeurs spécifiques d'énumération C++.

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 permettant d’accéder à une API non-Qt. Cette commande sert à supprimer les avertissements qui pourraient autrement être générés pour les membres d’une telle classe.