Textmarkierung

Die Befehle zur Textformatierung legen fest, wie der Text dargestellt werden soll.

\a (Parametermarkierung)

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

Es wird eine Warnung ausgegeben, wenn ein formaler Parameter nicht dokumentiert oder falsch geschrieben ist. Wenn Sie also eine Funktion dokumentieren, sollten Sie jeden formalen Parameter namentlich in der Funktionsbeschreibung erwähnen, wobei dem Parameternamen der Befehl ` \a ` vorangestellt wird. Der Parametername wird dann kursiv dargestellt.

Der Name des formalen Parameters kann in geschweifte Klammern gesetzt werden, dies ist jedoch nicht erforderlich.

\c (Code-Schriftart)

Der Befehl „ \c “ dient dazu, Variablennamen, benutzerdefinierte Klassennamen und C++-Schlüsselwörter (z. B. „ int “ und „ for “) in der Code-Schriftart darzustellen.

Der Befehl stellt sein Argument mit einer Monospace-Schriftart dar. Wenn der in der Code-Schriftart darzustellende Text Leerzeichen enthält, setzen Sie den gesamten Text in geschweifte Klammern:

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

Der Befehl „ \c “ akzeptiert das Sonderzeichen „ \ “ in seinem Argument, wodurch dieses als normales Zeichen dargestellt wird. Wenn Sie also verschachtelte Befehle verwenden möchten, müssen Sie stattdessen den Befehl „teletype“ (\tt) verwenden.

Siehe auch \tt und \code.

\details (ein- und ausklappbar)

Die Befehle „ \details “ und „ \enddetails “ erzeugen ein ein- und ausklappbares <details>-Element mit einem <summary>, um den Ein- und Ausblendstatus zu steuern.

Verwenden Sie bei der Erzeugung der HTML-Ausgabe die Befehle „ \details “ und „ \enddetails “, um ein ein- und ausklappbares HTML-Element „ <details> “ zu erzeugen. Der Befehl akzeptiert eine optionale Zusammenfassung, die in geschweifte Klammern gesetzt ist. Dieses optionale Argument gibt eine sichtbare Überschrift für die Details an.

Wird das Argument weggelassen, gibt QDoc „...“ als Zusammenfassungszeichenfolge aus.

Beispielsweise bei folgender Eingabe:

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

Wenn QDoc HTML generiert, wandelt es diese Befehle wie folgt um:

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

QDoc rendert dies wie folgt:

Bei allen anderen Ausgabeformaten generiert QDoc den Inhalt als normalen Absatz und ignoriert dabei die Zusammenfassungszeichenfolge. Dieser Befehl wurde in Qt 6.6 in QDoc eingeführt.

\div

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

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

Beispielsweise möchten wir vielleicht ein Inline-Bild so darstellen, dass es rechts neben dem aktuellen Textblock schwebt:

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

Wenn QDoc HTML generiert, wandelt es diese Befehle wie folgt um:

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

Bei HTML bezieht sich der Attributwert „float-right“ dann auf eine Anweisung in der Datei „style.css“, die in diesem Fall wie folgt lauten könnte:

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

Nachfolgend finden Sie ein Beispiel aus der Datei „index.qdoc“, die zur Erstellung von „index.html“ für Qt 4.7 verwendet wird:

\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 „class“-Attribute so definiert sind, wie sie in der Datei „style.css“ stehen, 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, wobei jedes Argument in geschweiften Klammern steht, wie im folgenden QDoc-Kommentar gezeigt. Das erste Argument wird nicht interpretiert, sondern gibt die Formatierungsattribute des von QDoc ausgegebenen Tags an. Das zweite Argument ist der Text, der mit den speziellen Formatierungsattributen dargestellt werden soll.

Beispielsweise möchten wir vielleicht 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“ bezieht sich 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 dargestellt:

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 (Marke)

Der Befehl „ \tm “ gibt an, dass sein Argument ein Markenzeichen ist. QDoc fügt bei der Erstellung einer Seite ein Markenzeichen-Symbol `™` an die erste Stelle des Arguments an.

In der Projektkonfiguration wird die Variable ` navigation.trademarkspage ` verwendet, um den Titel einer Seite zu definieren, die Dokumentation zu Markenzeichen enthält.

navigation.trademarkspage = Trademarks

Ist diese Variable gesetzt, ist jedes Vorkommen des Markenzeichens zudem mit der Seite „Marken“ verlinkt.

Siehe auch \section1 und navigation.

\tt (Teletype-Schriftart)

Der Befehl „ \tt “ gibt sein Argument in einer Monospace-Schriftart wieder. Dieser Befehl verhält sich genau wie der \c Befehl, mit dem Unterschied, dass „ \tt “ das Verschachteln 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 dargestellt werden soll, Leerzeichen enthält, setzen Sie den gesamten Text in geschweifte Klammern.

\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 hieß früher „ \bold “.

/*!
    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 “ rendert sein Argument in einer speziellen Schriftart, normalerweise kursiv. Dieser Befehl hieß früher „ \i “, was mittlerweile veraltet ist.

Wenn das Argument Leerzeichen oder andere Satzzeichen enthält, setzen Sie es in geschweifte Klammern.

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

Wenn Sie andere QDoc-Befehle innerhalb eines Arguments verwenden möchten, das Leerzeichen enthält, müssen Sie das Argument immer in geschweifte Klammern setzen. QDoc ist jedoch intelligent genug, um Klammern zu erkennen, sodass 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 am Ende eines Arguments stehende Satzzeichen ebenso wenig berücksichtigt wie „'s“.

\sub

Der Befehl „ \sub “ stellt sein Argument unterhalb der Grundlinie des regulären Textes dar und verwendet dabei 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, setzen Sie es in geschweifte Klammern.

\sup

Der Befehl „ \sup “ stellt sein Argument höher als die Grundlinie des normalen Textes dar und verwendet dabei 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, setzen Sie es in geschweifte Klammern.

\uicontrol

Der Befehl „ \uicontrol “ wird verwendet, um Inhalte als für UI-Steuerelemente bestimmt zu kennzeichnen. Bei Verwendung von HTML wird die Ausgabe fett dargestellt.

Siehe auch \b.

\underline

Der Befehl „ \underline “ stellt sein Argument unterstrichen dar.

/*!
    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, setzen Sie es in geschweifte Klammern.

\\ (doppelter Backslash)

Die Zeichenfolge \\ wird zu einem einzelnen Backslash erweitert.

QDoc-Befehle beginnen immer mit einem einzelnen 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 Ihr Text jedoch auch in einer Monospace-Schriftart angezeigt werden soll, können Sie stattdessen den \c Befehl verwenden, der den Backslash wie jedes andere Zeichen akzeptiert und darstellt. 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\}.
*/

-- (Halbgeviertstrich)

QDoc rendert doppelte Bindestriche als En-Bindestrich. QDoc-Markup-Befehle, die dafür ausgelegt sind, ihre Eingabe wörtlich wiederzugeben – wie beispielsweise der Befehl „ \c “ – ersetzen die doppelten Bindestriche nicht durch ein En-Bindestrich-Zeichen. Zum Beispiel:

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

Andere Befehle erfordern jedoch möglicherweise, dass die Bindestriche mit einem Escape-Zeichen versehen werden, um sicherzustellen, dass QDoc die Ausgabe wie erwartet darstellt. 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 --- (Langstrich).

--- (Langstrich)

QDoc rendert drei Bindestriche als Gedankenstrich. QDoc-Markup-Befehle, die dafür ausgelegt sind, ihre Eingabe wörtlich wiederzugeben – wie beispielsweise der Befehl „ \c “ –, ersetzen die drei Bindestriche nicht durch ein Gedankenstrichzeichen. Zum Beispiel:

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

Andere Befehle erfordern jedoch möglicherweise, dass die Bindestriche mit einem Escape-Zeichen versehen werden, um sicherzustellen, dass QDoc die Ausgabe wie erwartet darstellt. 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 -- (Halbgeviertstrich).