Inclusion de code en ligne

Les commandes suivantes sont utilisées pour rendre le code source sans formatage. Le code source commence sur une nouvelle ligne, rendue dans le code.

\code

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

Pour documenter des instructions de ligne de commande, des scripts shell ou tout contenu qui n'est pas dans un langage Qt reconnu par QDoc, utilisez plutôt \badcode à la place.

Lors du traitement de la commande \code, QDoc supprime toute indentation commune aux blocs de code verbatim à l'intérieur d'un commentaire /*! ... */ 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 rendu 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 liens automatiques

La commande \code tente d'analyser son contenu en tant que code d'une langue spécifique, telle que définie dans la variable de configuration de la langue. Cela permet de mettre en évidence et de lier automatiquement les types détectés dans le code.

Exceptionnellement, 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 en tant que QML ; pour les autres rubriques, c'est la variable de configuration du langage qui prévaut. Pour marquer explicitement l'extrait de code comme QML, utilisez plutôt la commande \qml à la place.

Depuis la version 6.11, une langue peut être spécifiée en tant qu'argument facultatif insensible à la casse sur la même ligne que la commande \code. Lorsqu'elle est spécifiée, la langue remplace la langue par défaut et tout autre comportement spécifique à la langue décrit ci-dessus. QDoc définit également le langage text afin que les blocs de code puissent être affichés sans balisage ni surlignage.

Par exemple :

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

Cela peut être utile lorsque l'on cite un langage que QDoc n'a pas la possibilité de baliser.

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

Paramètres de l'extrait de code

Depuis la version 5.12 de QDoc, la commande \code accepte également des paramètres optionnels. Les paramètres sont utiles pour injecter des chaînes simples dans l'extrait de code. Pour injecter une chaîne de caractères à un endroit précis du code, ajoutez une barre oblique inverse suivie d'un chiffre (1..8). Les chiffres correspondent à l'ordre de la liste d'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
*/

Dans l'extrait ci-dessus, QDoc rend le mot hello entouré d'un commentaire de style C.

Intégration de code provenant de fichiers externes

Pour inclure des extraits de code provenant d'un fichier externe, utilisez les balises \snippet et \codeline pour inclure des extraits de code provenant d'un fichier externe.

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

\badcode

Similaire à \codeles commandes \badcode et \endcode contiennent un contenu qui est rendu textuellement dans un paragraphe séparé, mais aucune analyse ou création de lien automatique n'est effectuée. Le contenu est traité comme du texte brut.

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

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

\qml

Les commandes \qml et \endqml contiennent un extrait de code source QML. Elles permettent de mettre en évidence la syntaxe des extraits de code QML. L'extrait joint 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
*/

Comme la commande \code\qml accepte des paramètres facultatifs.