Inclure du code externe

Les commandes suivantes vous permettent d'inclure des extraits de code provenant de fichiers externes. Vous pouvez faire en sorte que QDoc inclue le contenu complet d'un fichier, ou vous pouvez citer des parties spécifiques du fichier et en ignorer d'autres. Dans ce dernier cas, il s'agit généralement de citer un fichier morceau par morceau.

\quotefile

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

La commande considère le reste de la ligne comme faisant partie de son argument, assurez-vous de faire suivre le nom du fichier d'un saut de ligne.

Le contenu du fichier est présenté dans un paragraphe séparé, en utilisant une police monospace et l'indentation standard. Le code est affiché mot pour mot.

/*!
   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.
*/

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 \quotefile. Cela influence le texte cité de la même manière que pour la commande \code .

Par exemple :

\quotefile [text] examples/main.cpp

Cela peut être utile pour citer un fichier contenant un code source que QDoc n'a pas la possibilité de baliser.

Voir aussi \quotefromfile et \code.

\quotefromfile

La commande \quotefromfile ouvre le fichier donné en argument pour le citer.

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

Cette commande est destinée à être utilisée pour citer des parties de fichiers avec les commandes suivantes : , , , , , , , , , , , , , , , , : \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Cela vous permet de citer des parties 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 se souvient du fichier qu'il cite et de la position actuelle dans ce fichier (voir \printline pour plus d'informations). Il n'est pas nécessaire de "fermer" le fichier.

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 \quotefromfile. Cela influence le texte cité de la même manière que pour la commande \code .

Par exemple :

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

QDoc se souvient également du langage de code qu'il cite, de sorte que des commandes telles que \printline, \printto et \printuntil citent le fichier en cours, 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 s'étend à la ligne à partir de la position actuelle.

Pour s'assurer 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, assurez-vous de faire suivre la sous-chaîne d'un saut de ligne.

La ligne du fichier source est rendue comme un paragraphe séparé, en utilisant une police monospace et l'indentation standard. Le code est affiché mot pour mot.

/*!
   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 actuelle, vous pouvez utiliser l'une des commandes \skip.... Pour reculer la position actuelle, vous pouvez utiliser à nouveau la commande \quotefromfile à nouveau.

Si l'argument de la sous-chaîne est entouré 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.
*/

(Le fichier d'exemple complet...)

L'expression régulière /^\}/ fait en sorte que QDoc imprime jusqu'au premier caractère '}' en début de ligne sans indentation. /.../ entoure l'expression régulière, et '^' signifie 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 émet un avertissement si la sous-chaîne ou l'expression régulière spécifiée est introuvable, c'est-à-dire si le code source a été modifié.

Voir aussi \printto et \printuntil.

\printto

La commande \printto étend le texte à toutes les lignes à partir de la position actuelle jusqu'à la ligne suivante contenant une sous-chaîne donnée, à l'exclusion de cette dernière.

La commande considère le reste de la ligne comme faisant partie de son argument, assurez-vous de 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 commande \printline en matière de positionnement et d'arguments.

Les lignes du fichier source sont présentées dans un paragraphe séparé, en utilisant une police monospace et l'indentation standard. Le code est affiché mot pour mot.

/*!
   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 étend le texte à toutes les lignes à partir de la position actuelle jusqu'à la ligne suivante contenant une sous-chaîne donnée.

La commande considère le reste de la ligne comme faisant partie de son argument, assurez-vous de 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 commande \printline en matière de positionnement et d'arguments.

Si \printuntil est utilisé sans argument, il s'étend à toutes les lignes à partir de la position actuelle jusqu'à la fin du fichier cité.

Les lignes du fichier source sont présentées dans un paragraphe séparé, en utilisant une police monospace et l'indentation standard. Le code est affiché mot pour mot.

/*!
   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 prochaine ligne non vide dans le fichier source actuel.

Doc lit le fichier séquentiellement, et la commande \skipline est utilisée pour déplacer la position actuelle (en omettant une ligne du fichier source). Voir la remarque sur le positionnement des fichiers ci-dessus.

La commande considère le reste de la ligne comme faisant partie de son argument, assurez-vous de faire suivre la sous-chaîne d'un saut de ligne. La commande suit également les mêmes conventions pour les arguments que la commande \printline et elle est utilisée conjointement avec la commande \quotefromfile et s'utilise en conjonction avec la 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 à partir de la position actuelle jusqu'à la ligne suivante contenant une sous-chaîne donnée.

QDoc lit le fichier séquentiellement et la commande \skipto est utilisée pour déplacer la position actuelle (en omettant une ou plusieurs lignes du fichier source). Voir la remarque sur le positionnement des fichiers ci-dessus.

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

La commande suit également les mêmes conventions pour les arguments que la commande \printline et elle est utilisée conjointement avec la commande \quotefromfile et s'utilise en conjonction avec la 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 aussi \skipline, \skipuntil et \dots.

\skipuntil

La commande \skipuntil ignore toutes les lignes à partir de la position actuelle jusqu'à la prochaine ligne contenant une sous-chaîne donnée.

QDoc lit le fichier séquentiellement et la commande \skipuntil est utilisée pour déplacer la position actuelle (en omettant une ou plusieurs lignes du fichier source). Voir la remarque sur le positionnement des fichiers ci-dessus.

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

La commande suit également les mêmes conventions pour les arguments que la commande \printline et elle est utilisée conjointement avec la commande \quotefromfile et s'utilise en conjonction avec la 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 des parties du fichier source ont été omises lors de la citation d'un fichier.

Cette commande est utilisée conjointement avec la commande \quotefromfile et doit être énoncée sur sa propre ligne. Les points sont affichés sur une nouvelle ligne, en utilisant une police monospaciale.

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

L'indentation par défaut est de 4 espaces, mais elle peut être ajustée en utilisant l'argument optionnel 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 sous forme de texte préformaté, qui peut être mis en évidence par la syntaxe.

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 à l'intérieur du répertoire de documentation (par exemple, $QTDIR/doc/src/snippets).

Par exemple, la documentation suivante fait référence à un extrait de code dans un fichier résidant 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. Il est utilisé pour délimiter le code cité dans le fichier de l'extrait concerné, 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 d'extrait de code. Pour les fichiers .pro, .py, .cmake, et CMakeLists.txt, #! est détecté. Enfin, <!-- est accepté dans les fichiers .html, .qrc, .ui, .xml et .xq.

QDoc normalise l'indentation des extraits en comparant l'indentation spatiale 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 désindente ensuite automatiquement le corps de l'extrait en fonction de l'indentation la plus petite, garantissant que le code généré préserve toujours sa structure naturelle, quelle que soit la position des marqueurs. Les marqueurs sous-indentés ne sont pas modifiés.

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 \snippet. Cela influence le texte cité de la même manière que pour la commande \code .

Cet exemple d'utilisation de la commande ignore le style de balisage C++ par défaut et produit du texte brut à la place :

\snippet [text] code.cpp

Cela peut être utile pour citer un langage que QDoc ne peut pas baliser, ou pour citer un fichier dont le nom n'est pas conventionnel.

\codeline

La commande \codeline insère une ligne vierge de texte préformaté. Elle est utilisée pour insérer des espaces entre des extraits sans fermer la zone de texte préformaté en cours et en ouvrir une nouvelle.