Balisage du texte

Les commandes de mise en forme du texte indiquent comment le texte doit être rendu.

\a (marqueur de paramètre)

La commande \a indique à QDoc que le mot suivant est un nom de paramètre formel.

Un avertissement est émis lorsqu'un paramètre formel n'est pas documenté ou est mal orthographié. Lorsque vous documentez une fonction, vous devez donc 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 est alors rendu en italique.

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

\c (police de code)

La commande \c est utilisée pour rendre les noms de variables, les noms de classes définies par l'utilisateur et les mots-clés C++ (par exemple, int et for) dans la police de code.

La commande rend son argument en utilisant une police monospace. Si le texte à rendre dans la police de code contient des espaces, il doit être placé entre crochets :

\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. Par conséquent, si vous souhaitez utiliser des commandes imbriquées, vous devez utiliser la commande télétype (\tt ) à la place.

Voir aussi \tt et \code.

\details (repliable)

Les commandes \details et \enddetails génèrent un élément <details> repliable avec un <summary> pour contrôler l'état caché/visible.

Lors de la génération d'une sortie HTML, utilisez les commandes \details et \enddetails pour générer un élément HTML <details> repliable. La commande prend en compte une chaîne de caractères de résumé facultative entre accolades. Cet argument facultatif spécifie un titre visible pour les détails.

Par exemple, avec l'entrée suivante :

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

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

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

QDoc rend ceci comme :

Pour tout autre format de sortie, QDoc génère le contenu comme un paragraphe normal, en ignorant la chaîne de résumé. Cette commande a été introduite dans QDoc dans Qt6.6.

\div

Les commandes \div et \enddiv délimitent un petit ou grand bloc de texte (qui peut inclure d'autres commandes QDoc) auquel des attributs de formatage spéciaux 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 est utilisé comme attribut(s) de la balise produite par QDoc.

Par exemple, nous pourrions vouloir rendre une image en ligne de manière à ce qu'elle flotte à droite du bloc de texte actuel :

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

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

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

Pour HTML, la valeur de l'attribut float-right renvoie alors à une clause du fichier style.css, qui dans ce cas pourrait être :

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

Vous trouverez ci-dessous un exemple tiré du fichier index.qdoc utilisé pour générer 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 elles le sont dans le fichier style.css utilisé pour le rendu de la documentation Qt, l'exemple ci-dessus est rendu comme suit :

Voir aussi \span.

\span

La commande \span applique un formatage spécial à un petit bloc de texte.

Deux arguments doivent être fournis, chacun d'eux étant placé entre accolades, comme le montre le commentaire QDoc ci-dessous. Le premier argument n'est pas interprété, mais spécifie le(s) attribut(s) de formatage de la balise produite par QDoc. Le second argument est le texte à rendre avec les attributs de formatage spéciaux.

Par exemple, nous pourrions vouloir rendre le premier mot de chaque élément d'une liste numérique en bleu.

/*!
    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 variable de classe Nom fait référence à une clause de votre fichier style.css.

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

En utilisant la clause variableName montrée ci-dessus, l'exemple est rendu comme suit :

Variables globales avec 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 un symbole de marque ™` à 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 est utilisée pour définir le titre d'une page contenant de la documentation relative à une marque.

navigation.trademarkspage = Trademarks

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

Voir aussi \section1 et navigation.

\tt (police télétype)

La commande \tt rend son argument dans une police monospaciale. Cette commande se comporte comme la commande \c sauf que \tt vous permet d'imbriquer des commandes QDoc dans l'argument (par ex. \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 à rendre dans la police de code contient des espaces, il faut le mettre entre crochets.

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

Voir aussi \c.

\b

La commande \b rend son argument en caractères 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 retour à la ligne.

\e (accentuation, italique)

La commande \e rend son argument dans une police spéciale, normalement 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, il doit être placé entre crochets.

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

Si vous souhaitez utiliser d'autres commandes QDoc dans un argument contenant des espaces, vous devez toujours placer l'argument entre accolades. Mais QDoc est suffisamment intelligent pour compter les parenthèses, de sorte que vous n'avez pas besoin d'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 de fin n'est pas incluse dans un argument, pas plus que les "'s".

\sub

La commande \sub rend son argument plus bas que 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, il doit être placé entre crochets.

\sup

La commande \sup rend 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, il doit être placé entre crochets.

\uicontrol

La commande \uicontrol est utilisée pour marquer le contenu comme étant utilisé pour les éléments de contrôle de l'interface utilisateur. Lors de l'utilisation de HTML, la sortie est rendue en gras.

Voir aussi \b.

\underline

La commande \underline rend 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, il doit être placé entre crochets.

\N- (double barre oblique inverse)

La séquence \\N se développe en une seule barre oblique inverse.

Les commandes QDoc commencent toujours par une barre oblique inverse. Pour afficher une seule barre oblique inverse dans le texte, vous devez taper deux barres obliques inverses. Si vous voulez afficher deux barres obliques inverses, 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 apparaisse également dans une police monospaciale, vous pouvez utiliser la commande \c qui accepte et rend la barre oblique inverse 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 en)

QDoc rend les doubles traits d'union comme un tiret en. Les commandes de balisage de QDoc conçues pour que leur entrée apparaisse mot pour mot, comme la commande \c, ne remplaceront pas les doubles traits d'union par un tiret. Par exemple :

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

Cependant, d'autres commandes peuvent exiger que les traits d'union soient échappés pour que QDoc rende la sortie 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 --- (em dash).

--- (trait d'union)

QDoc rend les triples traits d'union comme un tiret em. Les commandes de balisage de QDoc conçues pour que leurs entrées apparaissent mot pour mot, comme la commande \c, ne remplacent pas les triples traits d'union par un trait d'union. Par exemple :

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

Cependant, d'autres commandes peuvent exiger que les traits d'union soient échappés pour que QDoc rende la sortie 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 -- (tiret en).