Intégration de code externe

Les commandes suivantes vous permettent d'inclure des extraits de code provenant de fichiers externes. Vous pouvez demander à QDoc d'inclure l'intégralité du contenu d'un fichier, ou bien de ne citer que certaines parties du fichier et d'en ignorer d'autres. Cette dernière option est généralement utilisée pour citer un fichier par blocs.

\quotefile

La commande ` \quotefile ` développe le contenu complet du fichier fourni en argument.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez donc à faire suivre le nom du fichier d’un saut de ligne.

Le contenu du fichier est affiché dans un paragraphe distinct, en utilisant une police à espacement fixe et l'indentation standard. Le code est affiché tel quel.

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

À 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 « \quotefile ». Cela influence le texte entre guillemets de la même manière que pour la \code commande.

Par exemple :

\quotefile [text] examples/main.cpp

Cela peut s'avérer utile lorsque vous citez un extrait d'un fichier contenant du code source que QDoc n'est pas en mesure de baliser.

Voir aussi \quotefromfile et \code.

\quotefromfile

La commande « \quotefromfile » ouvre le fichier indiqué en argument pour le mettre entre guillemets.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez donc à faire suivre le nom du fichier d’un saut de ligne.

Cette commande est destinée à être utilisée pour citer des extraits d'un fichier à l'aide des commandes de navigation : \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Cela vous permet de citer des passages spécifiques d'un fichier.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc mémorise le fichier dont provient la citation, ainsi que la position actuelle dans ce fichier (voir \printline pour plus d’informations). Il n’est pas nécessaire de « fermer » le fichier.

À partir de la version 6.11, une langue peut être spécifiée en tant qu’argument facultatif (sans distinction de majuscules/minuscules) sur la même ligne que la commande \quotefromfile. Cela influence le texte cité de la même manière que pour la \code commande.

Par exemple :

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDoc mémorise également le langage de code dont il extrait des extraits, ce qui permet d’utiliser des commandes telles que \printline, \printto et \printuntil sont extraites du fichier actuel, en appliquant un style de balisage cohérent jusqu’à ce qu’un nouveau fichier soit lu.

Voir aussi \quotefile, \code et \dots.

\printline

La commande « \printline » se développe en ligne à partir de la position courante.

Pour garantir que la documentation reste synchronisée avec le fichier source, une sous-chaîne de la ligne doit être spécifiée comme argument de la commande. Notez que la commande considère le reste de la ligne comme faisant partie de son argument ; veillez donc à faire suivre la sous-chaîne d’un saut de ligne.

La ligne du fichier source est affichée sous forme de paragraphe distinct, en utilisant une police à espacement fixe et l'indentation standard. Le code est affiché tel quel.

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc lit le fichier de manière séquentielle. Pour avancer la position courante, vous pouvez utiliser l'une des commandes suivantes :\skip... Pour reculer la position courante, vous pouvez utiliser à nouveau la \quotefromfile commande à nouveau.

Si l'argument « substring » est encadré de barres obliques, il est interprété comme un « regular expression ».

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(Fichier d'exemple complet...)

L'expression régulière /^\}/ indique à QDoc d'afficher jusqu'au premier caractère « } » apparaissant au début d'une ligne sans indentation. /.../ encadre l'expression régulière, et « ^ » désigne le début de la ligne. Le caractère « } » doit être échappé car il s'agit d'un caractère spécial dans les expressions régulières.

QDoc émettra un avertissement si la sous-chaîne ou l'expression régulière spécifiée ne peut être localisée, c'est-à-dire si le code source a été modifié.

Voir aussi \printto et \printuntil.

\printto

La commande « \printto » sélectionne toutes les lignes situées entre la position courante et la ligne suivante contenant une sous-chaîne donnée (cette dernière étant exclue ).

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez donc à faire suivre la sous-chaîne d’un saut de ligne. La commande suit également les mêmes conventions de positionnement et d’argument que la \printline commande.

Les lignes du fichier source sont affichées dans un paragraphe distinct, en utilisant une police à espacement fixe et l'indentation standard. Le code est affiché tel quel.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

Voir aussi \printline et \printuntil.

\printuntil

La commande « \printuntil » permet d’afficher toutes les lignes situées entre la position courante et la ligne suivante contenant une sous-chaîne donnée, incluse.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez donc à faire suivre la sous-chaîne d'un retour à la ligne. La commande suit également les mêmes conventions de positionnement et d'argument que la \printline commande.

Si la commande « \printuntil » est utilisée sans argument, elle s'applique à toutes les lignes comprises entre la position courante et la fin du fichier entre guillemets.

Les lignes du fichier source sont affichées dans un paragraphe distinct, en utilisant une police à espacement fixe et l'indentation standard. Le code est affiché tel quel.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

Voir aussi \printline et \printto.

\skipline

La commande « \skipline » ignore la ligne suivante non vide du fichier source actuel.

Doc lit le fichier de manière séquentielle, et la commande « \skipline » sert à déplacer la position courante (en omettant une ligne du fichier source). Voir la remarque ci-dessus concernant le positionnement dans le fichier.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez à faire suivre la sous-chaîne d'un saut de ligne. La commande suit également les mêmes conventions pour les arguments que la \printline commande, et elle est utilisée conjointement avec la \quotefromfile commande.

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

Voir aussi \skipto, \skipuntil et \dots.

\skipto

La commande « \skipto » ignore toutes les lignes situées entre la position courante et la ligne suivante contenant une sous-chaîne donnée (cette dernière étant exclue ).

QDoc lit le fichier de manière séquentielle, et la commande « \skipto » sert à déplacer la position courante (en omettant une ou plusieurs lignes du fichier source). Voir la remarque ci-dessus concernant le positionnement dans le fichier.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez à faire suivre la sous-chaîne d’un saut de ligne.

La commande suit également les mêmes conventions pour les arguments que la \printline commande, et elle s'utilise conjointement avec la \quotefromfile commande.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

Voir également \skipline, \skipuntil et \dots.

\skipuntil

La commande « \skipuntil » ignore toutes les lignes situées entre la position courante et la ligne suivante contenant une sous-chaîne donnée, cette dernière incluse.

QDoc lit le fichier de manière séquentielle, et la commande « \skipuntil » sert à déplacer la position courante (en omettant une ou plusieurs lignes du fichier source). Voir la remarque ci-dessus concernant le positionnement dans le fichier.

La commande considère le reste de la ligne comme faisant partie de son argument ; veillez à faire suivre la sous-chaîne d'un saut de ligne.

La commande suit également les mêmes conventions pour les arguments que la \printline commande, et elle s'utilise conjointement avec la \quotefromfile commande.

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

Voir aussi \skipline, \skipto et \dots.

\dots

La commande « \dots » indique que certaines parties du fichier source ont été omises lors de la citation d’un fichier.

Cette commande s’utilise en association avec la \quotefromfile commande et doit figurer sur une ligne distincte. Les points sont affichés sur une nouvelle ligne, en police à espacement fixe.

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

L'indentation par défaut est de 4 espaces, mais elle peut être modifiée à l'aide de l'argument facultatif de la commande.

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

Voir aussi \skipline, \skipto et \skipuntil.

\snippet

La commande ` \snippet ` permet d’inclure un extrait de code tel quel sous forme de texte préformaté, qui peut bénéficier d’une coloration syntaxique.

Chaque extrait de code est référencé par le fichier qui le contient et par un identifiant unique pour ce fichier. Les fichiers d'extraits sont généralement stockés dans un répertoire « snippets » situé à l'intérieur du répertoire « documentation » (par exemple, $QTDIR/doc/src/snippets).

QDoc utilise le premier fichier correspondant qu’il trouve. Lorsqu’un même chemin relatif existe dans plusieurs répertoires de recherche, QDoc consulte les répertoires dans l’ordre lexicographique des chemins, ce qui signifie qu’un fichier peut prendre le pas sur un autre.

Par exemple, la documentation suivante fait référence à un extrait de code contenu dans un fichier situé dans un sous-répertoire du répertoire de documentation :

\snippet snippets/textdocument-resources/main.cpp Adding a resource

Le texte qui suit le nom du fichier est l’identifiant unique de l’extrait de code. Il sert à délimiter le code entre guillemets dans le fichier d’extrait correspondant, comme le montre l’exemple suivant qui correspond à la commande \snippet ci-dessus :

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

Par défaut, QDoc recherche « //! » comme marqueur de snippet de code. Pour les fichiers « .pro », « .py », « .cmake » et « CMakeLists.txt », c’est « #! » qui est détecté. Enfin, « <!-- » est accepté dans les fichiers « .html », « .qrc », « .ui », « .xml » et « .xq ».

QDoc normalise l'indentation des extraits de code en comparant l'indentation basée sur les espaces du marqueur d'extrait à l'indentation minimale du contenu de l'extrait (en ignorant les macros Qt, les lignes vides et les commentaires sur toute la ligne). Il réduit ensuite automatiquement l’indentation du corps de l’extrait pour l’aligner sur la plus petite des deux, garantissant ainsi que le code généré conserve toujours sa structure naturelle, quel que soit l’emplacement des marqueurs. Les marqueurs sous-indentés ne sont pas modifiés.

À partir de la version 6.11, un langage peut être spécifié en tant qu’argument facultatif (insensible à la casse) sur la même ligne que la commande « \snippet ». Cela influence le texte entre guillemets de la même manière que pour la commande \code commande.

Cet exemple d'utilisation de la commande remplace le style de balisage C++ par défaut et génère à la place du texte brut :

\snippet [text] code.cpp

Cela peut s'avérer utile pour citer un langage que QDoc ne peut pas baliser, ou lorsqu'il est nécessaire de citer un extrait provenant d'un fichier dont le nom n'est pas conventionnel.

\codeline

La commande « \codeline » insère une ligne vide de texte préformaté. Elle sert à insérer des espaces entre des extraits de code sans fermer la zone de texte préformaté actuelle ni en ouvrir une nouvelle.