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

\abstract est un synonyme de la commande \qmlabstract. Ajoutez cette commande au commentaire \qmltype d'un type QML lorsque ce type est destiné à être utilisé uniquement en tant que 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é par \qmlabstract, il 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é comme interne, il aura une page de référence dans la documentation.

\Nattribution

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 la 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 conjointement avec la commande \class.

\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.

\Comparaison avec

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 étant la 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.

Remarque : L'énumération C++ doit être documentée dans le même projet ; QDoc ne peut pas accéder à sa documentation si elle fait partie d'un ensemble de documents externes que le projet actuel ne peut pas utiliser. depends actuel.

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)
*/

\Ndans le fichier d'en-tête

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

Par défaut, QDoc documente une page \class SomeClass pour qu'elle 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 qu'une fonction est dépréciée et qu'elle ne doit plus être utilisée dans le nouveau code. Il n'y a aucune garantie quant à la durée pendant laquelle elle restera dans la bibliothèque.

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éera une page séparée documentant ses fonctions obsolètes et établira un lien vers cette page. C'est une bonne pratique de suggérer une fonction équivalente comme alternative.

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

\interne

La commande \internal indique que la fonction référencée ne fait pas partie de l'interface publique.

La commande doit être placée 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 :

/*!
    \module QtFoo
    \modulestate Technical Preview
*/

QDoc ajoutera cette information sur la page du module :

Ce module est à l'état d'aperçu technique.

Note : N'utilisez pas cette commande pour déprécier un module. Utilisez plutôt la commande \deprecated.

Dans la sortie HTML, cette information sur l'état apparaît également dans la barre de navigation (breadcrumbs) des pages de référence pour les membres du module.

\preliminary

La commande \preliminary permet d'indiquer qu'une fonction référencée est encore en cours de développement.

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

La commande \preliminary se développe en une notification dans la documentation de la fonction, et marque la fonction comme préliminaire lorsqu'elle apparaît dans les 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);
}

\Lecture seule

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és.

\since

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

Si l'argument passé à \since ne contient pas d'espaces, il est supposé être une notation abrégée pour le nom du produit, et QDoc préfixera 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.

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.