Création de liens

Ces commandes permettent de créer des liens hypertextes vers des classes, des fonctions, des exemples et d'autres cibles.

\l (lien)

La commande \l link permet de créer un lien hypertexte vers différents types de cibles. La syntaxe générale de la commande est la suivante

\l [ link criteria ] { link target } { link text }

...où les link criteria entre crochets sont facultatifs mais peuvent être nécessaires lorsque les link target sont ambigus. Voir la section Correction des liens ambigus ci-dessous.

Vous pouvez utiliser la commande \l pour créer un lien vers :

• une page externe :

  An URL with a custom link text:
  \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.

  Rendus comme :

  Une URL avec un texte de lien personnalisé : Qt 6 Documentation.

  Une URL sans texte de lien personnalisé : http://doc.qt.io/qt-6/.

  Voir aussi \externalpage.

• une page de documentation. La cible du lien peut être :
  • le titre de la page spécifié avec la commande \title avec la commande

    Here is a link with a custom link text:
    \l {Getting Started with QDoc}{QDoc - Getting Started}.
    
    Here is a link with a link text that is the same as the link
    target: \l {Getting Started with QDoc}.

    Rendus comme :

    Voici un lien avec un texte de lien personnalisé : QDoc - Getting Started.

    Voici un lien dont le texte est identique à la cible du lien : Démarrer avec QDoc.

  • le nom du fichier de la page spécifié avec la commande \page commande :

    \page 08-qdoc-commands-creatinglinks.html
    \title Creating Links
    
    These commands are for creating hyperlinks to classes, functions,
    examples, and other targets.
    
    ...
    
    The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
    explains how to create links with QDoc.

    Rendu sous forme de :

    L'article de la page Création de liens explique comment créer des liens avec QDoc.

  • la page avec une \keyword commande.
• une section d'ancrage particulière dans un document. La cible du lien peut être
  • un titre de section spécifié avec l'une des commandes Section:

    Here is a link to a QDoc Commands section of the Writing
    Documentation topic:
    \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
    
    If you have unique section titles across your documentation
    project, you can use the section title as a target without
    the need to add the topic title:
    \l {QDoc Commands}.

    Rendue comme :

    Voici un lien vers une section QDoc Commands de la rubrique Writing Documentation : Commandes QDoc.

    Si vous avez des titres de section uniques dans votre projet de documentation, vous pouvez utiliser le titre de la section comme cible sans avoir besoin d'ajouter le titre de la rubrique : QDoc Commands.

  • une ancre définie par une \target commande :

    \target assertions
    
    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.
    
    ...
    
    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.

• un élément de l'API. Les liens cibles peuvent être
  • \l QWidget - le nom d'une classe documentée avec la commande \class ou \qmltype documentée.
  • \l QWidget::sizeHint() - La signature d'une fonction sans paramètres. Si une fonction correspondante sans paramètres ne peut être trouvée, le lien est satisfait par la première fonction correspondante trouvée.
  • \l QWidget::removeAction(QAction* action) - La signature d'une fonction avec paramètres. Si une correspondance exacte n'est pas trouvée, le lien n'est pas satisfait et QDoc signale une erreur " Can't link to...".
  • \l <QtGlobal> - Le sujet d'une \headerfile commande.
• un exemple. Le lien cible est le titre de l'exemple ou un chemin relatif utilisé dans une \example commande :

  /*!
      \example widgets/imageviewer
      \title ImageViewer Example
      \brief Shows how to combine QLabel and QScrollArea
      to display an image.
  
      ...
  */
  
  ...
  
  See the example: \l widgets/imageviewer

Si la cible du lien est équivalente au texte du lien, vous pouvez omettre le deuxième argument.

Par exemple, si vous avez une documentation comme :

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

Vous pouvez la simplifier comme suit :

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

Pour la version à un paramètre, les accolades peuvent souvent être omises.

QDoc essaie également de créer un lien à partir de tout mot qui ne ressemble pas à un mot anglais normal, par exemple, les noms de classes ou de fonctions Qt, comme QWidget ou QWidget::sizeHint(). Dans ces cas, la commande \l peut être omise, mais en utilisant la commande, vous vous assurez que QDoc émettra un avertissement s'il ne peut pas trouver la cible du lien. En outre, si vous souhaitez que seul le nom de la fonction apparaisse dans le lien, vous pouvez utiliser la syntaxe suivante :

• \l {QWidget::} {sizeHint()}

Correction des liens ambigus

Un lien ambigu est un lien qui a une cible correspondante dans plus d'un module Qt ou d'un ensemble de documentation. Par exemple, le même titre de section peut apparaître dans plus d'un module Qt, ou le nom d'une classe C++ dans un module peut également être le nom d'un type QML dans un autre module. Un exemple réel dans Qt est le nom Qt lui-même : c'est à la fois le nom d'un espace de noms C++ dans QtCore et d'un type QML dans QtQml.

Supposons que nous voulions créer un lien vers le site Qt C++ namespace. Au moment où QDoc a généré cette page HTML, ce lien était correct. Va-t-il toujours vers l'espace de noms C++ ? Qdoc a généré ce lien à partir de la commande link :

• \l {Qt} {Qt C++ namespace}

Supposons maintenant que nous voulions créer un lien vers le site Qt QML type. Au moment où QDoc a généré cette page HTML, ce lien était également correct, mais nous avons dû utiliser cette commande de lien :

• \l [QML] {Qt} {Qt QML type}

Le QML entre crochets indique à QDoc de n'accepter une cible correspondante que si celle-ci se trouve sur une page QML. En fait, QDoc trouve d'abord la cible de l'espace de noms C++, mais comme cette cible se trouve sur une page C++, QDoc l'ignore et continue à chercher jusqu'à ce qu'il trouve la même cible sur une page QML.

Sans les indications de la commande\l dans l'argument optionnel des crochets, QDoc établit un lien vers la première cible correspondante qu'il trouve. Dans ce cas, QDoc ne peut pas signaler que le lien est ambigu, car il ne sait pas s'il existe une autre cible correspondante.

Quels arguments peuvent figurer entre crochets ?

Une commande de lien avec un argument entre crochets a la syntaxe suivante :

\l [QML|CPP|DOC|attached|QtModuleName] {link target} {link text}

L'argument des crochets n'est autorisé que dans la commande \l (link). L'exemple ci-dessus montre comment QML est utilisé comme argument entre crochets pour forcer QDoc à correspondre à une cible QML. Le plus souvent, il s'agit d'un type QML, mais il peut également s'agir d'une fonction membre ou d'une propriété QML. En outre, certains types QML contiennent des propriétés et des propriétés attachées portant le même nom. Les propriétés attachées peuvent être sélectionnées à l'aide de l'argument attached. Si attached est omis, les propriétés normales seront liées de préférence aux propriétés attachées avec des noms dupliqués.

Dans l'exemple, QDoc n'a pas eu besoin d'un argument de type crochet pour trouver la page de l'espace de noms Qt C++, car c'était la première cible correspondante que QDoc avait trouvée de toute façon. Cependant, pour forcer QDoc à trouver une cible C++ lorsqu'une cible QML correspondante se trouve sur le chemin, CPP peut être utilisé comme argument de crochet. Par exemple, le lien suivant forcera QDoc à ignorer le type Qt QML et à poursuivre la recherche jusqu'à ce qu'il trouve l'espace de noms Qt C++.

• \l [CPP] {Qt} {Qt C++ namespace}

Si la cible du lien n'est ni une entité C++ ni une entité QML, DOC peut être utilisé comme argument de crochet pour empêcher QDoc de correspondre à l'une ou l'autre de ces entités. Au moment de la rédaction de ce document, il n'y avait pas de cas de liens ambigus pour lesquels l'utilisation de DOC était nécessaire.

Souvent, le documenteur sait dans quel module Qt se trouve la cible du lien. Lorsque le nom du module est connu, il faut utiliser le nom du module comme argument du crochet. Dans l'exemple ci-dessus, si nous savons que le type QML nommé Qt se trouve dans le module QtQml, nous pouvons écrire la commande de lien comme suit :

• \l [QtQml] {Qt} {Qt QML type}

Lorsqu'un nom de module est utilisé comme argument entre crochets, QDoc recherche la cible du lien dans ce module uniquement. Cela rend la recherche des cibles de lien plus efficace.

Enfin, les arguments "nom de module" et "type d'entité" peuvent être combinés, séparés par un blanc, de sorte que ce type d'argument est également autorisé :

• \l [CPP QtQml] {Window} {C++ class Window}

Au moment de la rédaction de ce document, il n'y avait aucun cas où il était nécessaire de combiner les deux.

Voir aussi \sa, \target, et \keyword.

\sa (voir aussi)

La commande \sa définit une liste de liens qui seront affichés dans une section distincte "Voir aussi" au bas de l'unité de documentation.

La commande prend comme argument une liste de liens séparés par des virgules. Si la ligne se termine par une virgule, vous pouvez continuer la liste sur la ligne suivante. La syntaxe générale est la suivante :

\sa {the first link}, {the second link},
    {the third link}, ...

QDoc essaiera automatiquement de générer des liens "Voir aussi" reliant les différentes fonctions d'une propriété. Par exemple, une fonction setVisible() obtiendra automatiquement un lien vers visible() et vice versa.

En général, QDoc génère des liens "Voir aussi" qui interconnectent les fonctions qui accèdent à la même propriété. Il reconnaît quatre versions syntaxiques différentes :

• property()
• setProperty()
• isProperty()
• hasProperty()

La commande \sa prend en charge le même type de liens que la commande \l La commande prend en charge le même type de liens que la commande

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

Voir aussi \l, \target et \keyword.

\target

La commande \target désigne un endroit de la documentation auquel vous pouvez accéder à l'aide des commandes \l (lien) et \sa (voir aussi).

Le texte jusqu'au saut de ligne devient le nom de la cible. Veillez à faire suivre le nom de la cible d'un saut de ligne. Les crochets ne sont pas nécessaires autour du nom de la cible, mais ils peuvent l'être lorsque le nom de la cible est utilisé dans une commande de lien. Voir ci-dessous.

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

Le nom de la cible capturant les parenthèses peut être lié de la manière suivante :

• \l {capturing parentheses}

Ci-dessus, le nom de la cible est mis entre parenthèses parce qu'il contient des espaces.

\target dans un \table

Lorsque vous utilisez la commande \target dans un tableau, assurez-vous que la commande \target suit une commande \li-(cellule de tableau), car certains générateurs ne prennent en charge que les cibles d'une cellule individuelle, et non d'une ligne entière. De plus, assurez-vous qu'elle se trouve sur une ligne séparée ou qu'elle est le dernier contenu de la ligne dans laquelle elle se trouve. Cela est dû à la façon dont la commande \target fonctionne ; elle consomme tout ce qui se trouve jusqu'au prochain saut de ligne en tant que paramètre. En d'autres termes, si vous avez un tableau et que vous avez besoin d'un \target à l'intérieur de celui-ci, veillez à ce qu'il suive la structure suivante :

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

Voir aussi \l, \sa et \keyword.

\keyword

La commande \keyword nomme un endroit de la documentation auquel vous pouvez accéder à l'aide des commandes \l (lien) et \sa (voir aussi). Elle ajoute également le mot-clé et l'emplacement aux index générés.

La commande \keyword est similaire à la commande \target sauf que lorsqu'elle renvoie à un mot-clé, le lien va par défaut au début du commentaire QDoc (sujet) dans lequel \keyword apparaît.

Si vous souhaitez créer un mot-clé pour une unité section au sein d'un sujet, ajoutez le \keyword directement au-dessus du titre de la section :

\keyword debug
\section1 Debug command line option (--debug)
...

Contrairement à \target, les mots-clés sont enregistrés dans les index des fichiers de documentation hors ligne générés (.qch). Cela permet aux utilisateurs de rechercher l'emplacement par mot-clé, par exemple dans la recherche d'index deQt Assistant, et rend le mot-clé accessible dans l'aide contextuelle de Qt Creator.

Les mots-clés doivent être uniques pour tous les documents traités au cours de l'exécution de QDoc. La commande utilise le reste de la ligne comme argument. Veillez à faire suivre le mot-clé d'un saut de ligne.

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

L'emplacement marqué par le mot-clé peut être relié à l'aide de :

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

Si le texte du mot-clé contient des espaces, les crochets sont nécessaires.

Voir aussi \l (lien), \sa (voir aussi) et \target.