Textauszeichnung

Die Befehle zur Textformatierung geben an, wie der Text wiedergegeben werden soll.

\a (Parametermarkierung)

Der Befehl \a teilt QDoc mit, dass das nächste Wort ein formaler Parametername ist.

Eine Warnung wird ausgegeben, wenn ein formaler Parameter nicht dokumentiert oder falsch geschrieben ist. Wenn Sie eine Funktion dokumentieren, sollten Sie daher jeden formalen Parameter in der Funktionsbeschreibung namentlich erwähnen, wobei der Befehl \a vorangestellt wird. Der Parametername wird dann in kursiver Schrift dargestellt.

Der Name des Formalparameters kann in geschweifte Klammern eingeschlossen werden, dies ist jedoch nicht erforderlich.

\c (Code-Schriftart)

Der Befehl \c dient der Darstellung von Variablennamen, benutzerdefinierten Klassennamen und C++-Schlüsselwörtern (z. B. int und for) in der Code-Schriftart.

Der Befehl rendert sein Argument unter Verwendung einer Monospace-Schriftart. Wenn der in der Code-Schriftart wiederzugebende Text Leerzeichen enthält, schließen Sie den gesamten Text in geschweifte Klammern ein:

\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) : QWidget(parent)}

Der Befehl \c akzeptiert das Sonderzeichen \ in seinem Argument, das als normales Zeichen wiedergegeben wird. Wenn Sie also verschachtelte Befehle verwenden wollen, müssen Sie stattdessen den Befehl teletype (\tt) verwenden.

Siehe auch \tt und \code.

\details (einklappbar)

Die Befehle \details und \enddetails erzeugen ein zusammenklappbares <details>-Element mit einem <summary>, um den verborgenen/sichtbaren Zustand zu steuern.

Bei der Erzeugung von HTML-Ausgaben verwenden Sie die Befehle \details und \enddetails, um ein einklappbares <details> HTML-Element zu erzeugen. Der Befehl nimmt eine optionale, in geschweifte Klammern eingeschlossene Zusammenfassungszeichenfolge entgegen. Dieses optionale Argument gibt eine sichtbare Überschrift für die Details an.

Zum Beispiel mit der folgenden Eingabe:

/*!
    \details {QDoc details}
      \note You're looking at detailed information.
    \enddetails
*/

Wenn QDoc HTML generiert, wird es diese Befehle in übersetzen:

<summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div>

QDoc rendert dies als:

Für jedes andere Ausgabeformat generiert QDoc den Inhalt als normalen Absatz und ignoriert die Zusammenfassung. Dieser Befehl wurde in QDoc in Qt6.6 eingeführt.

\div

Die Befehle \div und \enddiv grenzen einen großen oder kleinen Textblock ab (der auch andere QDoc-Befehle enthalten kann), auf den spezielle Formatierungsattribute angewendet werden sollen.

Ein Argument muss in geschweiften Klammern angegeben werden, wie in dem unten gezeigten QDoc-Kommentar. Das Argument wird nicht interpretiert, sondern als Attribut(e) des Tags verwendet, das von QDoc ausgegeben wird.

Zum Beispiel könnte man ein Inline-Bild so darstellen, dass es rechts vom aktuellen Textblock schwebt:

/*!
    \div {class="float-right"}
        \inlineimage qml-column.png
    \enddiv
*/

Wenn QDoc HTML generiert, wird es diese Befehle in übersetzen:

<div class="float-right"><p><img src="images/qml-column.png" /></p></div>

Bei HTML verweist der Attributwert float-right dann auf eine Klausel in der Datei style.css, die in diesem Fall lauten könnte:

div.float-right
{
   float: right; margin-left: 2em
}

Nachfolgend finden Sie ein Beispiel aus der Datei index.qdoc, die zur Erzeugung von index.html für Qt 4.7 verwendet wurde:

\div {class="indexbox guide"}
    \div {class="heading"}
        Qt Developer Guide
\enddiv
    \div {class="indexboxcont indexboxbar"}
        \div {class="section indexIcon"} \emptyspan
        \enddiv
        \div {class="section"}
            Qt is a cross-platform application and UI
            framework. Using Qt, you can write web-enabled
            applications once and deploy them across desktop,
            mobile and embedded operating systems without
            rewriting the source code.
        \enddiv
        \div {class="section sectionlist"}
            \list
               \li \l{Getting Started}
               \li \l{Installation} {Installation}
               \li \l{how-to-learn-qt.html} {How to learn Qt}
               \li \l{tutorials.html} {Tutorials}
               \li \l{Qt Examples} {Examples}
               \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
            \endlist
        \enddiv
    \enddiv
\enddiv

Wenn alle Werte der Klassenattribute so definiert sind, wie sie in der style.css-Datei definiert sind, die für die Darstellung der Qt-Dokumentation verwendet wird, wird das obige Beispiel wie folgt dargestellt:

Siehe auch \span.

\span

Der Befehl \span wendet eine spezielle Formatierung auf einen kleinen Textblock an.

Es müssen zwei Argumente angegeben werden, die jeweils in geschweiften Klammern stehen, wie im nachfolgenden QDoc-Kommentar gezeigt. Das erste Argument wird nicht interpretiert, sondern gibt das/die Formatierungsattribut(e) des von QDoc ausgegebenen Tags an. Das zweite Argument ist der Text, der mit den speziellen Formatierungsattributen wiedergegeben werden soll.

Zum Beispiel könnte man das erste Wort jedes Elements in einer numerischen Liste in blau darstellen.

/*!
    Global variables with complex types:
\list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
*/

Die Klasse variableName verweist auf eine Klausel in Ihrer style.css.

.variableName
{
    font-family: courier;
color: blue
}

Unter Verwendung der oben gezeigten variableName-Klausel wird das Beispiel wie folgt wiedergegeben:

Globale Variablen mit komplexen Typen:

1. mutableComplex1 in globals.cpp in Zeile 14
2. mutableComplex2 in globals.cpp in Zeile 15
3. constComplex1 in globals.cpp in Zeile 16
4. constComplex2 in globals.cpp in Zeile 17

Siehe auch \div.

\tm (Markenzeichen)

Der Befehl \tm zeigt an, dass sein Argument eine Marke ist. QDoc fügt beim Erzeugen einer Seite ein Markensymbol `™` an das erste Vorkommen des Arguments an.

In der Projektkonfiguration wird die Variable navigation.trademarkspage verwendet, um einen Titel für eine Seite zu definieren, die markenbezogene Dokumentation enthält.

navigation.trademarkspage = Trademarks

Wenn sie gesetzt ist, verweist jedes Vorkommen des Markensymbols auch auf die Markenseite.

Siehe auch \section1 und navigation.

\tt (Fernschreibschrift)

Der Befehl \tt stellt sein Argument in einer Monospace-Schriftart dar. Dieser Befehl verhält sich genauso wie der Befehl \c, mit dem Unterschied, dass \tt die Verschachtelung von QDoc-Befehlen innerhalb des Arguments erlaubt (z. B. \e, \b und \underline).

/*!
    After having populated the main container with
    child widgets, \c setupUi() scans the main container's list of
    slots for names with the form
    \tt{on_\e{objectName}_\e{signalName}().}
*/

Wenn der Text, der in der Code-Schriftart wiedergegeben werden soll, Leerzeichen enthält, schließen Sie den gesamten Text in geschweifte Klammern ein.

\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

Siehe auch \c.

\b

Der Befehl \b stellt sein Argument in fetter Schrift dar. Dieser Befehl wurde früher \bold genannt.

/*!
    This is regular text; \b {this text is
    rendered using the \\b command}.
*/

\br

Der Befehl \br erzwingt einen Zeilenumbruch.

\e (Hervorhebung, Kursivschrift)

Der Befehl \e stellt sein Argument in einer speziellen Schriftart dar, normalerweise kursiv. Dieser Befehl hieß früher \i, der jetzt veraltet ist.

Wenn das Argument Leerzeichen oder andere Satzzeichen enthält, schließen Sie das Argument in geschweifte Klammern ein.

/*!
    Here, we render \e {a few words} in italics.
*/

Wenn Sie andere QDoc-Befehle innerhalb eines Arguments verwenden wollen, das Leerzeichen enthält, müssen Sie das Argument immer in geschweifte Klammern einschließen. Aber QDoc ist schlau genug, um Klammern zu zählen, so dass Sie in Fällen wie diesem keine geschweiften Klammern benötigen:

/*!
    An argument can sometimes contain whitespaces,
    for example: \e QPushButton(tr("A Brand New Button"))
*/

Schließlich werden abschließende Satzzeichen nicht in ein Argument eingeschlossen, ebenso wenig wie "'s".

\sub

Der Befehl \sub setzt sein Argument unter die Grundlinie des normalen Textes und verwendet eine kleinere Schriftart.

/*!
    Definition (Range): Consider the sequence
    {x\sub n}\sub {n > 1} . The set

    {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}

    is called the range of the sequence.
*/

Wenn das Argument Leerzeichen oder andere Satzzeichen enthält, schließen Sie das Argument in geschweifte Klammern ein.

\sup

Der Befehl \sup setzt sein Argument höher als die Grundlinie des normalen Textes und verwendet eine kleinere Schriftart.

/*!
    The series

    1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...

    is called the \i {geometric series}.
*/

Wenn das Argument Leerzeichen oder andere Satzzeichen enthält, schließen Sie das Argument in geschweifte Klammern ein.

\uicontrol

Der Befehl \uicontrol wird verwendet, um Inhalte als für UI-Steuerelemente verwendet zu markieren. Bei der Verwendung von HTML wird die Ausgabe in Fettdruck wiedergegeben.

Siehe auch \b.

\underline

Der Befehl \underline macht sein Argument unterstrichen.

/*!
    The \underline {F}ile menu gives the users the possibility
    to edit an existing file, or save a new or modified
    file, and exit the application.
*/

Wenn das Argument Leerzeichen oder andere Satzzeichen enthält, schließen Sie das Argument in geschweifte Klammern ein.

\\ (doppelter Backslash)

Die Folge \\ wird zu einem einfachen Backslash expandiert.

QDoc-Befehle beginnen immer mit einem einfachen Backslash. Um einen einzelnen Backslash im Text anzuzeigen, müssen Sie zwei Backslashes eingeben. Wenn Sie zwei Backslashes anzeigen möchten, müssen Sie vier eingeben.

/*!
    The \\\\ command is useful if you want a
    backslash to appear verbatim, for example,
    writing C:\\windows\\home\\.
*/

Wenn Sie jedoch möchten, dass Ihr Text auch in einer Monospace-Schriftart erscheint, können Sie stattdessen den Befehl \c verwenden, der den Backslash wie jedes andere Zeichen akzeptiert und wiedergibt. Zum Beispiel:

/*!
    The \\c command is useful if you want a
    backslash to appear verbatim, and the word
    that contains it written in a monospace font,
    like this: \c {C:\windows\home\}.
*/

-- (Bindestrich)

QDoc stellt doppelte Bindestriche als Bindestriche dar. QDoc-Auszeichnungsbefehle, die darauf abzielen, dass ihre Eingaben wortwörtlich erscheinen - wie z.B. der \c-Befehl - ersetzen die doppelten Bindestriche nicht durch ein en dash-Zeichen. Zum Beispiel:

/*!
    The \\c command -- useful if you want text in a monospace font --
    is well documented.
*/

Andere Befehle können jedoch verlangen, dass die Bindestriche maskiert werden, um sicherzustellen, dass QDoc die Ausgabe wie erwartet rendert. Zum Beispiel;

/*!
    This \l {endash-sequence}{link to the -- (endash) sequence}
    isn't escaped and QDoc therefore renders an endash in the link
    text. However, the escaped
    \l {endash-sequence}{link to the \-- (endash) sequence}
    renders both hyphens as intended.
*/

Siehe auch --- (em-Bindestrich).

--- (Bindestrich)

QDoc stellt dreifache Bindestriche als Bindestriche dar. QDoc-Auszeichnungsbefehle, die darauf ausgelegt sind, dass ihre Eingaben wortwörtlich erscheinen - wie z.B. der Befehl \c - ersetzen die dreifachen Bindestriche nicht durch einen Bindestrich. Zum Beispiel:

/*!
    The \\c command---useful when you want text to be rendered
    verbatim---is well documented.
*/

Bei anderen Befehlen kann es jedoch erforderlich sein, die Bindestriche zu escapen, um sicherzustellen, dass QDoc die Ausgabe wie erwartet rendert. Zum Beispiel;

/*!
    This \l {emdash-sequence}{link to the --- (emdash) sequence}
    isn't escaped and QDoc therefore renders an emdash in the link
    text. However, the escaped
    \l {emdash-sequence}{link to the -\-- (emdash) sequence}
    renders both hyphens as intended.
*/

Siehe auch -- (Bindestrich).