Externen Code einbinden

Mit den folgenden Befehlen können Sie Codeausschnitte aus externen Dateien einbinden. Sie können QDoc den gesamten Inhalt einer Datei einbinden lassen oder bestimmte Teile der Datei zitieren und andere überspringen. Letzteres wird typischerweise verwendet, um eine Datei abschnittsweise zu zitieren.

\quotefile

Der Befehl „ \quotefile “ erweitert sich zum vollständigen Inhalt der als Argument angegebenen Datei.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie daher darauf, nach dem Dateinamen einen Zeilenumbruch einzufügen.

Der Inhalt der Datei wird in einem separaten Absatz dargestellt, wobei eine Monospace-Schriftart und die Standard-Einrückung verwendet werden. Der Code wird wörtlich wiedergegeben.

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

Ab Version 6.11 kann eine Sprache als optionales, groß-/kleinschreibungsunabhängiges Argument in derselben Zeile wie der Befehl „ \quotefile “ angegeben werden. Dies wirkt sich auf den zitierten Text genauso aus wie beim Befehl \code Befehl.

Beispiel:

\quotefile [text] examples/main.cpp

Dies kann nützlich sein, wenn aus einer Datei zitiert wird, die Quellcode enthält, den QDoc nicht auswerten kann.

Siehe auch \quotefromfile und \code.

\quotefromfile

Der Befehl „ \quotefromfile “ öffnet die als Argument angegebene Datei zur Quotierung.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie daher darauf, nach dem Dateinamen einen Zeilenumbruch einzufügen.

Der Befehl ist für die Verwendung vorgesehen, wenn Teile aus einer Datei mit den Walkthrough-Befehlen zitiert werden sollen: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Auf diese Weise können Sie bestimmte Abschnitte einer Datei zitieren.

/*!
   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 merkt sich, aus welcher Datei zitiert wird, sowie die aktuelle Position in dieser Datei (siehe \printline für weitere Informationen). Es ist nicht erforderlich, die Datei zu „schließen“.

Ab Version 6.11 kann eine Sprache als optionales Argument (Groß-/Kleinschreibung wird nicht berücksichtigt) in derselben Zeile wie der Befehl „ \quotefromfile “ angegeben werden. Dies wirkt sich auf den zitierten Text genauso aus wie beim \code Befehl.

Beispiel:

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

QDoc merkt sich außerdem, aus welcher Programmiersprache das Zitat stammt, sodass Befehle wie \printline, \printto und \printuntil aus der aktuellen Datei zitiert und wendet dabei einen einheitlichen Markup-Stil an, bis eine neue Datei eingelesen wird.

Siehe auch \quotefile, \code und \dots.

\printline

Der Befehl „ \printline “ erweitert sich auf die Zeile ab der aktuellen Position.

Um sicherzustellen, dass die Dokumentation mit der Quelldatei synchron bleibt, muss ein Teilstring der Zeile als Argument für den Befehl angegeben werden. Beachten Sie, dass der Befehl den Rest der Zeile als Teil seines Arguments betrachtet; stellen Sie daher sicher, dass auf den Teilstring ein Zeilenumbruch folgt.

Die Zeile aus der Quelldatei wird als separater Absatz dargestellt, wobei eine Monospace-Schriftart und die Standard-Einrückung verwendet werden. Der Code wird wörtlich wiedergegeben.

/*!
   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 liest die Datei sequenziell ein. Um die aktuelle Position vorwärts zu verschieben, können Sie einen der Befehle „\skip “ verwenden. Um die aktuelle Position rückwärts zu verschieben, können Sie den \quotefromfile Befehl erneut verwenden.

Wenn das Teilzeichenfolgen-Argument von Schrägstrichen umgeben ist, wird es als „ regular expression “ interpretiert.

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

(Die vollständige Beispieldatei...)

Der reguläre Ausdruck /^\}/ bewirkt, dass QDoc bis zum ersten „}“-Zeichen, das am Zeilenanfang ohne Einrückung steht, ausgibt. /.../ umschließt den regulären Ausdruck, und „^“ bedeutet den Zeilenanfang. Das „}“-Zeichen muss mit einem Escape-Zeichen versehen werden, da es in regulären Ausdrücken ein Sonderzeichen ist.

QDoc gibt eine Warnung aus, wenn die angegebene Teilzeichenfolge oder der reguläre Ausdruck nicht gefunden werden kann, d. h. wenn sich der Quellcode geändert hat.

Siehe auch \printto und \printuntil.

\printto

Der Befehl „ \printto “ erweitert sich auf alle Zeilen ab der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenfolge enthält (diese Zeile selbst wird dabei nicht mitgezählt ).

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie daher darauf, dass auf die Teilzeichenfolge ein Zeilenumbruch folgt. Der Befehl folgt hinsichtlich der Positionierung und der Argumente denselben Konventionen wie der \printline Befehl.

Die Zeilen aus der Quelldatei werden in einem separaten Absatz dargestellt, wobei eine Monospace-Schriftart und die Standard-Einrückung verwendet werden. Der Code wird wörtlich wiedergegeben.

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

Siehe auch \printline und \printuntil.

\printuntil

Der Befehl „ \printuntil “ erweitert sich auf alle Zeilen von der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenfolge enthält.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; stellen Sie daher sicher, dass auf die Teilzeichenfolge ein Zeilenumbruch folgt. Der Befehl folgt außerdem denselben Konventionen für die Positionierung und die Argumente wie der \printline Befehl.

Wird „ \printuntil “ ohne Argument verwendet, wird er auf alle Zeilen von der aktuellen Position bis zum Ende der in Anführungszeichen gesetzten Datei erweitert.

Die Zeilen aus der Quelldatei werden in einem separaten Absatz dargestellt, wobei eine Monospace-Schriftart und die Standard-Einrückung verwendet werden. Der Code wird wörtlich wiedergegeben.

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

Siehe auch \printline und \printto.

\skipline

Der Befehl „ \skipline “ ignoriert die nächste nicht leere Zeile in der aktuellen Quelldatei.

„Doc“ liest die Datei sequenziell, und der Befehl „ \skipline “ wird verwendet, um die aktuelle Position zu verschieben (wobei eine Zeile der Quelldatei übersprungen wird). Siehe den obigen Hinweis zur Dateipositionierung.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie darauf, dem Teilstring einen Zeilenumbruch folgen zu lassen. Der Befehl folgt zudem denselben Konventionen für Argumente wie der \printline Befehl und wird in Verbindung mit dem \quotefromfile Befehl verwendet.

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

Siehe auch \skipto, \skipuntil und \dots.

\skipto

Der Befehl „ \skipto “ ignoriert alle Zeilen ab der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenfolge enthält.

QDoc liest die Datei sequenziell, und der Befehl ` \skipto ` wird verwendet, um die aktuelle Position zu verschieben (wobei eine oder mehrere Zeilen der Quelldatei übersprungen werden). Siehe den Hinweis zur Dateipositionsbestimmung weiter oben.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie daher darauf, der Teilzeichenfolge einen Zeilenumbruch folgen zu lassen.

Der Befehl folgt zudem denselben Konventionen für Argumente wie der \printline Befehl und wird in Verbindung mit dem \quotefromfile Befehl verwendet.

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

Siehe auch \skipline, \skipuntil und \dots.

\skipuntil

Der Befehl „ \skipuntil “ ignoriert alle Zeilen von der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenfolge enthält.

QDoc liest die Datei sequenziell, und der Befehl „ \skipuntil “ wird verwendet, um die aktuelle Position zu verschieben (wobei eine oder mehrere Zeilen der Quelldatei übersprungen werden). Siehe den Hinweis zur Dateipositionierung weiter oben.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; achten Sie daher darauf, dass auf die Teilzeichenfolge ein Zeilenumbruch folgt.

Der Befehl folgt zudem denselben Konventionen für Argumente wie der \printline Befehl und wird in Verbindung mit dem \quotefromfile Befehl verwendet.

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

Siehe auch \skipline, \skipto und \dots.

\dots

Der Befehl „ \dots “ weist darauf hin, dass beim Einfügen einer Datei Teile der Quelldatei weggelassen wurden.

Der Befehl wird in Verbindung mit dem \quotefromfile Befehl und sollte in einer eigenen Zeile angegeben werden. Die Punkte werden in einer neuen Zeile unter Verwendung einer Monospace-Schriftart dargestellt.

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

Die Standard-Einrückung beträgt 4 Leerzeichen, kann jedoch mithilfe des optionalen Arguments des Befehls angepasst werden.

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

Siehe auch \skipline, \skipto und \skipuntil.

\snippet

Der Befehl „ \snippet “ bewirkt, dass ein Code-Schnipsel wörtlich als vorformatierter Text eingefügt wird, der möglicherweise syntaktisch hervorgehoben ist.

Jedes Code-Snippet wird über die Datei, in der es gespeichert ist, und über eine eindeutige Kennung für diese Datei referenziert. Snippet-Dateien werden in der Regel in einem Verzeichnis „ snippets “ innerhalb des Dokumentationsverzeichnisses gespeichert (zum Beispiel $QTDIR/doc/src/snippets).

QDoc verwendet die erste passende Datei, die es findet. Wenn derselbe relative Pfad in mehr als einem Suchverzeichnis vorhanden ist, durchläuft QDoc die Verzeichnisse in lexikografischer Pfadreihenfolge, sodass eine Datei eine andere überschreiben kann.

Beispielsweise verweist die folgende Dokumentation auf einen Codeausschnitt in einer Datei, die sich in einem Unterverzeichnis des Dokumentationsverzeichnisses befindet:

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

Der Text nach dem Dateinamen ist die eindeutige Kennung für den Codeausschnitt. Diese wird verwendet, um den zitierten Code in der entsprechenden Codeausschnitt-Datei abzugrenzen, wie im folgenden Beispiel gezeigt, das dem oben genannten Befehl „ \snippet “ entspricht:

    ...
    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]
    ...

Standardmäßig sucht QDoc nach „ //! “ als Markierung für Code-Snippets. Bei Dateien vom Typ „ .pro “, „ .py “, „ .cmake “ und „ CMakeLists.txt “ wird „ #! “ erkannt. Schließlich wird „ <!-- “ in Dateien vom Typ „ .html “, „ .qrc “, „ .ui “, „ .xml “ und „ .xq “ akzeptiert.

QDoc normalisiert die Einrückung von Codeausschnitten, indem es die auf Leerzeichen basierende Einrückung der Ausschnittmarkierung mit der minimalen Einrückung des Ausschnittinhalts vergleicht (wobei Qt-Makros, Leerzeilen und ganzzeilige Kommentare ignoriert werden). Anschließend wird der Snippet-Körper automatisch auf den jeweils kleineren Wert zurückgesetzt, wodurch sichergestellt wird, dass der generierte Code stets seine natürliche Struktur beibehält, unabhängig davon, wo sich die Marker befinden. Zu wenig eingerückte Marker bleiben unverändert.

Ab Version 6.11 kann eine Sprache als optionales, groß-/kleinschreibungsunabhängiges Argument in derselben Zeile wie der Befehl „ \snippet “ angegeben werden. Dies wirkt sich auf den in Anführungszeichen gesetzten Text genauso aus wie beim Befehl \code Befehl.

In diesem Anwendungsbeispiel wird der standardmäßige C++-Markup-Stil überschrieben und stattdessen Klartext ausgegeben:

\snippet [text] code.cpp

Dies kann nützlich sein, wenn eine Sprache zitiert wird, die QDoc nicht markieren kann, oder wenn aus einer Datei mit einem unüblichen Dateinamen zitiert werden muss.

\codeline

Der Befehl „ \codeline “ fügt eine Leerzeile mit vorformatiertem Text ein. Er wird verwendet, um Lücken zwischen Textabschnitten einzufügen, ohne den aktuellen vorformatierten Textbereich zu schließen und einen neuen zu öffnen.