Inclusion de code en ligne

Les commandes suivantes permettent d'afficher du code source sans mise en forme. Le code source commence sur une nouvelle ligne et s'affiche tel quel dans le texte.

\code

Les commandes \code et \endcode encadrent un extrait de code source.

Pour documenter des instructions de ligne de commande, des scripts shell ou tout contenu qui n’est pas rédigé dans un langage Qt reconnu par QDoc, utilisez \badcode à la place.

Lors du traitement de la commande \code, QDoc supprime toute indentation courante des blocs de code verbatim situés dans un commentaire de type /*! ... */ avant d’ajouter l’indentation standard.

/*!
    \code
        #include <QApplication>
        #include <QPushButton>

        int main(int argc, char *argv[])
        {
            ...
        }
    \endcode
*/

Les autres commandes QDoc sont désactivées dans \code... \endcode, et le caractère spécial « \ » est accepté et affiché comme le reste du code, sauf s'il est suivi d'un chiffre et que des paramètres ont été transmis à \code.

Mise en évidence et création automatique de liens

La commande \code tente d’analyser son contenu en tant que code d’un langage spécifique, tel que défini dans la variable de configuration de langage. Cela permet la mise en évidence et la création automatique de liens vers les types détectés dans le code.

À titre d’exception depuis la version 6.4 de QDoc, lorsque la commande ` \code ` est utilisée dans une rubrique spécifique à QML, QDoc tente d’abord de reconnaître le code comme du QML ; pour les autres rubriques, la variable de configuration de langage prévaut. Pour marquer explicitement l’extrait de code comme du QML, utilisez plutôt la \qml commande à la place.

À partir de la version 6.11, un langage peut être spécifié en tant qu’argument facultatif (sans distinction de majuscules/minuscules) sur la même ligne que la commande ` \code `. Lorsqu’il est spécifié, ce langage remplace le langage par défaut et tout autre comportement spécifique au langage décrit ci-dessus. QDoc définit également le langage ` text ` afin que les blocs de code puissent être affichés sans aucun balisage ni mise en évidence.

Par exemple :

\code [text]
    # This is an example of unmarked code.
    implement MyModule;
    include "sys.m";
    sys: Sys;
\endcode

Cela peut s’avérer utile lorsqu’on cite un langage que QDoc n’est pas en mesure de baliser.

Vous pouvez également spécifier un langage pour un bloc de code que QDoc ne reconnaît pas en incluant ce langage dans la liste gérée par la variable de configuration `codelanguages`. Cela permet d'inclure des métadonnées dans le code HTML généré, qui peuvent être utilisées par d'autres outils pour mettre en évidence la syntaxe du code.

Paramètres des extraits de code

Depuis la version 5.12 de QDoc, la commande ` \code ` accepte également des paramètres facultatifs. Ces paramètres sont utiles pour insérer des chaînes de caractères simples dans l’extrait de code. Pour insérer une chaîne à un emplacement précis dans l’extrait, ajoutez une barre oblique inversée suivie d’un chiffre (1 à 8). Les chiffres correspondent à l'ordre de la liste des arguments, où les arguments sont séparés par des espaces et suivent tout argument de langage facultatif.

Par exemple :

/*!
    \code * hello
    /\1 \2 \1/
    \endcode
*/

Pour l'extrait ci-dessus, QDoc affiche le mot « hello » entre les balises d'un commentaire de style C.

Inclusion de code provenant de fichiers externes

Pour inclure des extraits de code provenant d’un fichier externe, utilisez la balise \snippet et \codeline .

Voir aussi \c, \qml, \badcode, \quotefromfile, et la langue.

\badcode

À l’instar des \code, les commandes \badcode et \endcode encadrent un contenu qui est affiché tel quel dans un paragraphe distinct, mais aucune analyse syntaxique ni création automatique de liens n’est effectuée. Au lieu de cela, le contenu est traité comme du texte brut.

Remplacez \code par cette commande lorsque vous documentez des instructions de ligne de commande, des scripts de shell ou tout autre contenu qui n’est pas rédigé dans un langage Qt, mais qui doit néanmoins être mis en forme de la même manière qu’un paragraphe \code.

Tout comme \code, \badcode accepte également des paramètres facultatifs.

\qml

Les commandes \qml et \endqml encadrent un extrait de code source QML. Utilisez-les pour une mise en évidence syntaxique correcte des extraits de code QML. L'extrait encadré doit être complet, comme s'il s'agissait d'un fichier .qml valide. Si l'extrait est incomplet, QDoc émettra un avertissement et ignorera l'extrait.

/*!
    \qml
        import QtQuick 2.0

        Row {
            Rectangle {
                width: 100; height: 100
                color: "blue"
                transform: Translate { y: 20 }
            }
            Rectangle {
                width: 100; height: 100
                color: "red"
                transform: Translate { y: -20 }
            }
        }
    \endqml
*/

Tout comme la \code commande, \qml accepte des paramètres facultatifs.