Balisage du texte

Les commandes de mise en forme du texte indiquent comment celui-ci doit être affiché.

\a (marqueur de paramètre)

La commande « \a » indique à QDoc que le mot suivant est le nom d'un paramètre formel.

Un avertissement est émis lorsqu'un paramètre formel n'est pas documenté ou comporte une faute d'orthographe. Ainsi, lorsque vous documentez une fonction, vous devez mentionner chaque paramètre formel par son nom dans la description de la fonction, en le faisant précéder de la commande \a. Le nom du paramètre s'affiche alors en italique.

Le nom du paramètre formel peut être placé entre accolades, mais ce n'est pas obligatoire.

\c (police de code)

La commande ` \c ` permet d'afficher les noms de variables, les noms de classes définis par l'utilisateur et les mots-clés C++ (par exemple, ` int ` et ` for`) dans la police de code.

La commande affiche son argument à l'aide d'une police à espacement fixe. Si le texte à afficher en police de code contient des espaces, placez l'intégralité du texte entre accolades :

\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) : QWidget(parent)}

La commande « \c » accepte le caractère spécial « \ » dans son argument, ce qui le rend comme un caractère normal. Ainsi, si vous souhaitez utiliser des commandes imbriquées, vous devez utiliser la commande « teletype » (\tt) à la place.

Voir aussi \tt et \code.

\details (réductible)

Les commandes \details et \enddetails génèrent un élément <details> repliable avec un <summary> permettant de contrôler son état (masqué/visible).

Lors de la génération d’un code HTML, utilisez les commandes \details et \enddetails pour créer un élément HTML <details> repliable. La commande accepte une chaîne de résumé facultative placée entre accolades. Cet argument facultatif spécifie un titre visible pour les détails.

Si l’argument est omis, QDoc affiche « ... » comme chaîne de résumé.

Par exemple, avec l'entrée suivante :

/*!
    \details {QDoc details}
        \note You're looking at detailed information.
    \enddetails
*/

Si QDoc génère du code HTML, il traduira ces commandes en :

<details>
  <summary>QDoc details</summary>
  <div class="admonition note">
    <p><b>Note: </b>You're looking at detailed information.</p>
  </div>
</details>

QDoc affiche cela sous la forme suivante :

Pour tout autre format de sortie, QDoc génère le contenu sous forme de paragraphe normal, en ignorant la chaîne de résumé. Cette commande a été introduite dans QDoc à partir de Qt 6.6.

\div

Les commandes \div et \enddiv délimitent un bloc de texte plus ou moins long (pouvant inclure d'autres commandes QDoc) auquel des attributs de mise en forme spécifiques doivent être appliqués.

Un argument doit être fourni entre accolades, comme dans le commentaire QDoc ci-dessous. L’argument n’est pas interprété, mais sert d’attribut(s) à la balise générée par QDoc.

Par exemple, on peut souhaiter afficher une image en ligne de manière à ce qu’elle soit alignée à droite du bloc de texte actuel :

/*!
    \div {class="float-right"}
        \inlineimage qml-column.png
    \enddiv
*/

Si QDoc génère du code HTML, il traduira ces commandes comme suit :

<div class="float-right"><p><img src="images/qml-column.png" /></p></div>

En HTML, la valeur d’attribut « float-right » fera alors référence à une clause du fichier style.css, qui pourrait être, dans ce cas :

div.float-right
{
   float: right; margin-left: 2em
}

Vous trouverez ci-dessous un exemple tiré du fichier index.qdoc utilisé pour générer le fichier index.html pour Qt 4.7 :

\div {class="indexbox guide"}
    \div {class="heading"}
        Qt Developer Guide
\enddiv
    \div {class="indexboxcont indexboxbar"}
        \div {class="section indexIcon"} \emptyspan
        \enddiv
        \div {class="section"}
            Qt is a cross-platform application and UI
            framework. Using Qt, you can write web-enabled
            applications once and deploy them across desktop,
            mobile and embedded operating systems without
            rewriting the source code.
        \enddiv
        \div {class="section sectionlist"}
            \list
               \li \l{Getting Started}
               \li \l{Installation} {Installation}
               \li \l{how-to-learn-qt.html} {How to learn Qt}
               \li \l{tutorials.html} {Tutorials}
               \li \l{Qt Examples} {Examples}
               \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
            \endlist
        \enddiv
    \enddiv
\enddiv

Lorsque toutes les valeurs des attributs de classe sont définies comme dans le fichier style.css utilisé pour le rendu de la documentation Qt, l'exemple ci-dessus s'affiche comme suit :

Voir aussi \span.

\span

La commande « \span » applique une mise en forme spéciale à un petit bloc de texte.

Deux arguments doivent être fournis, chacun entre accolades, comme indiqué dans le commentaire QDoc ci-dessous. Le premier argument n’est pas interprété, mais spécifie le ou les attributs de mise en forme de la balise générée par QDoc. Le deuxième argument est le texte à afficher avec les attributs de mise en forme spéciaux.

Par exemple, on peut souhaiter afficher en bleu le premier mot de chaque élément d'une liste numérotée.

/*!
    Global variables with complex types:
\list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
*/

La classe ` variableName ` fait référence à une clause de votre fichier `style.css`.

.variableName
{
    font-family: courier;
color: blue
}

En utilisant la clause « variableName » indiquée ci-dessus, l'exemple s'affiche comme suit :

Variables globales de types complexes :

1. mutableComplex1 dans globals.cpp à la ligne 14
2. mutableComplex2 dans globals.cpp à la ligne 15
3. constComplex1 dans globals.cpp à la ligne 16
4. constComplex2 dans globals.cpp à la ligne 17

Voir aussi \div.

\tm (marque déposée)

La commande ` \tm ` indique que son argument est une marque déposée. QDoc ajoute le symbole de marque déposée `™` à la première occurrence de l'argument lors de la génération d'une page.

Dans la configuration du projet, la variable ` navigation.trademarkspage ` sert à définir le titre d'une page contenant de la documentation relative aux marques déposées.

navigation.trademarkspage = Trademarks

Si elle est définie, chaque occurrence du symbole de marque déposée renvoie également vers la page des marques déposées.

Voir aussi \section1 et navigation.

\tt (police de caractères téléscripteur)

La commande \tt affiche son argument dans une police à espacement fixe. Cette commande se comporte exactement comme la \c , à la différence près que ` \tt ` vous permet d’imbriquer des commandes QDoc au sein de l’argument (par exemple \e, \b et \underline).

/*!
    After having populated the main container with
    child widgets, \c setupUi() scans the main container's list of
    slots for names with the form
    \tt{on_\e{objectName}_\e{signalName}().}
*/

Si le texte à afficher dans la police du code contient des espaces, placez l'intégralité du texte entre accolades.

\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

Voir aussi \c.

\b

La commande « \b » affiche son argument en gras. Cette commande s'appelait auparavant « \bold ».

/*!
    This is regular text; \b {this text is
    rendered using the \\b command}.
*/

\br

La commande \br force un saut de ligne.

\e (mise en évidence, italique)

La commande ` \e ` affiche son argument dans une police spéciale, généralement en italique. Cette commande s'appelait auparavant ` \i`, qui est désormais obsolète.

Si l'argument contient des espaces ou d'autres signes de ponctuation, placez-le entre accolades.

/*!
    Here, we render \e {a few words} in italics.
*/

Si vous souhaitez utiliser d'autres commandes QDoc au sein d'un argument contenant des espaces, vous devez toujours placer cet argument entre accolades. Cependant, QDoc est suffisamment intelligent pour reconnaître les parenthèses ; vous n'avez donc pas besoin d'utiliser des accolades dans des cas comme celui-ci :

/*!
    An argument can sometimes contain whitespaces,
    for example: \e QPushButton(tr("A Brand New Button"))
*/

Enfin, la ponctuation finale n'est pas incluse dans un argument, pas plus que « 's ».

\sub

La commande ` \sub ` affiche son argument en dessous de la ligne de base du texte normal, en utilisant une police plus petite.

/*!
    Definition (Range): Consider the sequence
    {x\sub n}\sub {n > 1} . The set

    {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}

    is called the range of the sequence.
*/

Si l'argument contient des espaces ou d'autres signes de ponctuation, placez-le entre accolades.

\sup

La commande « \sup » affiche son argument plus haut que la ligne de base du texte normal, en utilisant une police plus petite.

/*!
    The series

    1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...

    is called the \i {geometric series}.
*/

Si l’argument contient des espaces ou d’autres signes de ponctuation, placez-le entre accolades.

\uicontrol

La commande « \uicontrol » permet de marquer du contenu comme étant utilisé pour les éléments de contrôle de l'interface utilisateur. En HTML, le texte s'affiche en gras.

Voir aussi \b.

\underline

La commande « \underline » affiche son argument souligné.

/*!
    The \underline {F}ile menu gives the users the possibility
    to edit an existing file, or save a new or modified
    file, and exit the application.
*/

Si l'argument contient des espaces ou d'autres signes de ponctuation, placez-le entre accolades.

\\ (double barre oblique inversée)

La séquence \\ se transforme en une seule barre oblique inversée.

Les commandes QDoc commencent toujours par une barre oblique inversée simple. Pour afficher une barre oblique inversée simple dans le texte, vous devez taper deux barres obliques inversées. Si vous souhaitez afficher deux barres obliques inversées, vous devez en taper quatre.

/*!
    The \\\\ command is useful if you want a
    backslash to appear verbatim, for example,
    writing C:\\windows\\home\\.
*/

Toutefois, si vous souhaitez que votre texte s'affiche également dans une police à espacement fixe, vous pouvez utiliser la \c commande à la place, qui accepte et affiche la barre oblique inversée comme n'importe quel autre caractère. Par exemple :

/*!
    The \\c command is useful if you want a
    backslash to appear verbatim, and the word
    that contains it written in a monospace font,
    like this: \c {C:\windows\home\}.
*/

-- (tiret long)

QDoc affiche les doubles tirets comme un tiret court. Les commandes de balisage QDoc conçues pour afficher le contenu tel quel — telles que la commande ` \c ` — ne remplaceront pas les doubles tirets par un tiret court. Par exemple :

/*!
    The \\c command -- useful if you want text in a monospace font --
    is well documented.
*/

Cependant, d'autres commandes peuvent nécessiter que les tirets soient échappés afin de garantir que QDoc affiche le résultat comme prévu. Par exemple :

/*!
    This \l {endash-sequence}{link to the -- (endash) sequence}
    isn't escaped and QDoc therefore renders an endash in the link
    text. However, the escaped
    \l {endash-sequence}{link to the \-- (endash) sequence}
    renders both hyphens as intended.
*/

Voir aussi --- (tiret long).

--- (trait d'union long)

QDoc affiche les trois tirets comme un tiret long. Les commandes de balisage QDoc conçues pour afficher le contenu tel quel — telles que la commande \c — ne remplacent pas les trois tirets par un tiret long. Par exemple :

/*!
    The \\c command---useful when you want text to be rendered
    verbatim---is well documented.
*/

Cependant, d’autres commandes peuvent nécessiter que les tirets soient échappés afin de garantir que QDoc affiche le résultat comme prévu. Par exemple :

/*!
    This \l {emdash-sequence}{link to the --- (emdash) sequence}
    isn't escaped and QDoc therefore renders an emdash in the link
    text. However, the escaped
    \l {emdash-sequence}{link to the -\-- (emdash) sequence}
    renders both hyphens as intended.
*/

Voir aussi -- (trait d’union court).