Code inline einbinden

Die folgenden Befehle dienen dazu, Quellcode ohne Formatierung darzustellen. Der Quellcode beginnt in einer neuen Zeile und wird im Code angezeigt.

\code

Die Befehle „ \code “ und „ \endcode “ umschließen einen Ausschnitt aus dem Quellcode.

Zur Dokumentation von Befehlszeilenanweisungen, Shell-Skripten oder anderen Inhalten, die nicht in einer von QDoc erkannten Qt-Sprache verfasst sind, verwenden Sie \badcode stattdessen.

Bei der Verarbeitung des Befehls „ \code “ entfernt QDoc alle Einrückungen, die für die wörtlichen Code-Blöcke innerhalb eines Kommentars vom Typ „ / “*!... */ üblich sind, bevor die Standardeinrückung hinzugefügt wird.

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

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

Andere QDoc-Befehle sind innerhalb von \code... \endcode deaktiviert, und das Sonderzeichen „\“ wird akzeptiert und wie der restliche Code dargestellt, es sei denn, es folgt eine Ziffer und es wurden Parameter an \code übergeben.

Hervorhebung und automatische Verlinkung

Der Befehl „ \code “ versucht, seinen Inhalt als Code einer bestimmten Sprache zu analysieren, wie in der Sprachkonfigurationsvariablen definiert. Dies ermöglicht die Hervorhebung und die automatische Verlinkung zu den im Code erkannten Typen.

Seit QDoc-Version 6.4 gilt jedoch folgende Ausnahme: Wird der Befehl „ \code “ innerhalb eines QML-spezifischen Themas verwendet, versucht QDoc zunächst, den Code als QML zu erkennen; bei anderen Themen hat die Sprachkonfigurationsvariable Vorrang. Um den Codeausschnitt explizit als QML zu kennzeichnen, verwenden Sie stattdessen den Befehl \qml Befehl.

Ab Version 6.11 kann eine Sprache als optionales, groß-/kleinschreibungsunabhängiges Argument in derselben Zeile wie der Befehl ` \code ` angegeben werden. Wenn angegeben, überschreibt die Sprache die Standardsprache und jedes andere oben beschriebene sprachspezifische Verhalten. QDoc definiert außerdem die Sprache ` text `, damit Code-Blöcke ohne jegliche Markierung oder Hervorhebung angezeigt werden können.

Beispiel:

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

Dies kann nützlich sein, wenn eine Sprache zitiert wird, die QDoc nicht markieren kann.

Alternativ können Sie eine Sprache für einen Code-Block angeben, den QDoc nicht erkennt, indem Sie die Sprache in die Liste der Konfigurationsvariable „codelanguages“ aufnehmen. Dadurch werden Metadaten in den generierten HTML-Code eingebunden, die von anderen Tools zur Syntaxhervorhebung des Codes verwendet werden können.

Parameter für Codeausschnitte

Seit QDoc-Version 5.12 akzeptiert der Befehl „ \code “ auch optionale Parameter. Parameter sind nützlich, um einfache Zeichenfolgen in das Code-Snippet einzufügen. Um eine Zeichenfolge an einer bestimmten Stelle im Snippet einzufügen, fügen Sie einen Backslash gefolgt von einer Ziffer (1..8) hinzu. Die Ziffern entsprechen der Reihenfolge in der Argumentliste, wobei die Argumente durch Leerzeichen getrennt sind und auf ein eventuelles optionales Sprachargument folgen.

Beispiel:

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

Für den obigen Ausschnitt rendert QDoc das Wort „hello“ in einem Kommentar im C-Stil.

Einbinden von Code aus externen Dateien

Um Codeausschnitte aus einer externen Datei einzubinden, verwenden Sie den Befehl \snippet und \codeline Befehle.

Siehe auch \c, \qml, \badcode, \quotefromfile, und Sprache.

\badcode

Ähnlich wie \codeschließen die Befehle \badcode und \endcode Inhalte ein, die wörtlich in einem separaten Absatz wiedergegeben werden, wobei jedoch keine Analyse oder automatische Linkerstellung erfolgt. Stattdessen wird der Inhalt als reiner Text behandelt.

Verwenden Sie diesen Befehl anstelle von ` \code `, wenn Sie Befehlszeilenanweisungen, Shell-Skripte oder andere Inhalte dokumentieren, die nicht in einer Qt-Sprache verfasst sind, aber dennoch ähnlich wie ein ` \code `-Absatz formatiert werden sollen.

Wie „ \code “ akzeptiert auch „ \badcode “ optionale Parameter.

\qml

Die Befehle „ \qml “ und „ \endqml “ umschließen einen Ausschnitt aus dem QML-Quellcode. Verwenden Sie diese Befehle für eine korrekte Syntaxhervorhebung von QML-Codeausschnitten. Der eingeschlossene Ausschnitt muss vollständig sein, als wäre er eine gültige .qml-Datei. Ist der Ausschnitt unvollständig, gibt QDoc eine Warnung aus und ignoriert den Ausschnitt.

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

Ähnlich wie der \code Befehl akzeptiert auch \qml optionale Parameter.