Links erstellen

Diese Befehle dienen zum Erstellen von Hyperlinks zu Klassen, Funktionen, Beispielen und anderen Zielen.

\l (Link)

Der Befehl \l (link) wird verwendet, um einen Hyperlink zu vielen verschiedenen Arten von Zielen zu erstellen. Die allgemeine Syntax des Befehls lautet:

\l [ link criteria ] { link target } { link text }

...wobei die link criteria in eckigen Klammern optional sind, aber erforderlich sein können, wenn die link target mehrdeutig ist. Siehe Mehrdeutige Links reparieren unten.

Sie können den Befehl \l verwenden, um zu verlinken:

• eine externe Seite:

  An URL with a custom link text:
  \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.

  Wird wiedergegeben als:

  Eine URL mit einem benutzerdefinierten Linktext: Qt 6-Dokumentation.

  Eine URL ohne benutzerdefinierten Linktext: http://doc.qt.io/qt-6/.

  Siehe auch \externalpage.

• eine Dokumentationsseite. Das Linkziel kann sein:
  • der mit dem Befehl \title angegebene Seitentitel:

    Here is a link with a custom link text:
    \l {Getting Started with QDoc}{QDoc - Getting Started}.
    
    Here is a link with a link text that is the same as the link
    target: \l {Getting Started with QDoc}.

    Wird wiedergegeben als:

    Hier ist ein Link mit einem benutzerdefinierten Linktext: QDoc - Erste Schritte.

    Hier ist ein Link mit einem Linktext, der mit dem Linkziel identisch ist: Erste Schritte mit QDoc.

  • der Name der Seitendatei, die mit dem \page-Befehl angegeben wurde:

    \page 08-qdoc-commands-creatinglinks.html
    \title Creating Links
    
    These commands are for creating hyperlinks to classes, functions,
    examples, and other targets.
    
    ...
    
    The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
    explains how to create links with QDoc.

    Wiedergegeben als:

    Der Artikel Links erstellen erklärt, wie man mit QDoc Links erstellt.

  • die Seite mit einem \keyword-Befehl.
• einen bestimmten Ankerabschnitt innerhalb eines Dokuments. Das Linkziel kann sein:
  • ein Abschnittstitel, der mit einem der Abschnittsbefehle angegeben wurde:

    Here is a link to a QDoc Commands section of the Writing
    Documentation topic:
    \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
    
    If you have unique section titles across your documentation
    project, you can use the section title as a target without
    the need to add the topic title:
    \l {QDoc Commands}.

    Wiedergegeben als:

    Hier ist ein Link zu einem Abschnitt von QDoc Commands im Thema Dokumentation schreiben: QDoc-Befehle.

    Wenn Sie in Ihrem Dokumentationsprojekt eindeutige Abschnittstitel haben, können Sie den Abschnittstitel als Ziel verwenden, ohne dass Sie den Titel des Themas hinzufügen müssen: QDoc-Befehle.

  • einen mit einem \target-Befehl definierten Anker:

    \target assertions
    
    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.
    
    ...
    
    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.

• ein API-Element. Zielverknüpfungen können sein:
  • \l QWidget - Der Name einer Klasse, die mit dem Befehl \class oder \qmltype dokumentiert ist.
  • \l QWidget::sizeHint() - Die Signatur einer Funktion ohne Parameter. Wenn keine passende Funktion ohne Parameter gefunden werden kann, wird die Verknüpfung mit der ersten gefundenen passenden Funktion erfüllt.
  • \l QWidget::removeAction(QAction* action) - Die Signatur einer Funktion mit Parametern. Wenn keine exakte Übereinstimmung gefunden wird, wird die Verknüpfung nicht erfüllt und QDoc meldet einen Can't link to... Fehler.
  • \l <QtGlobal> - Das Subjekt eines \headerfile-Befehls.
• ein Beispiel. Der Ziellink ist der Beispieltitel oder ein relativer Pfad, der in einem \example-Befehl verwendet wird:

  /*!
      \example widgets/imageviewer
      \title ImageViewer Example
      \brief Shows how to combine QLabel and QScrollArea
      to display an image.
  
      ...
  */
  
  ...
  
  See the example: \l widgets/imageviewer

Wenn das Linkziel mit dem Linktext übereinstimmt, können Sie das zweite Argument weglassen.

Zum Beispiel, wenn Sie eine Dokumentation wie die folgende haben:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

Sie können dies wie folgt vereinfachen:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

Bei der Ein-Parameter-Version können die geschweiften Klammern oft weggelassen werden.

QDoc versucht auch, aus jedem Wort, das nicht wie ein normales englisches Wort aussieht, einen Link zu machen, z.B. Qt-Klassennamen oder Funktionen, wie QWidget oder QWidget::sizeHint(). In diesen Fällen kann der \l-Befehl eigentlich weggelassen werden, aber durch die Verwendung des Befehls stellen Sie sicher, dass QDoc eine Warnung ausgibt, wenn es das Linkziel nicht finden kann. Wenn Sie wollen, dass nur der Funktionsname im Link erscheint, können Sie außerdem die folgende Syntax verwenden:

• \l {QWidget::} {sizeHint()}

Zweideutige Links reparieren

Aufgrund der Modularisierung von Qt ab Qt 5.0 ist die Möglichkeit, dass QDoc mit mehrdeutigen Links umgehen muss, gestiegen. Ein mehrdeutiger Link ist ein Link, der ein passendes Ziel in mehr als einem Qt-Modul hat, z.B. kann derselbe Abschnittstitel in mehr als einem Qt-Modul erscheinen, oder der Name einer C++-Klasse in einem Modul kann auch der Name eines QML-Typs in einem anderen Modul sein. Ein konkretes Beispiel in Qt5 ist der Name Qt selbst. Qt ist der Name sowohl eines C++-Namensraums in QtCore als auch eines QML-Typs in QtQml.

Nehmen wir an, wir wollen auf Qt C++ namespace verweisen. Als QDoc diese HTML-Seite generierte, war dieser Link korrekt. Führt er immer noch zum C++-Namensraum? Qdoc hat diesen Link mit diesem Link-Befehl erzeugt:

• \l {Qt} {Qt C++ namespace}

Nehmen wir nun an, wir wollen auf Qt QML type verlinken. Als QDoc diese HTML-Seite erzeugte, war dieser Link ebenfalls korrekt, aber wir mussten diesen Link-Befehl verwenden:

• \l [QML] {Qt} {Qt QML type}

Das QML in eckigen Klammern weist QDoc an, ein passendes Ziel nur dann zu akzeptieren, wenn sich das Ziel auf einer QML-Seite befindet. Tatsächlich findet QDoc zuerst das C++-Namensraumziel, aber da dieses Ziel auf einer C++-Seite ist, ignoriert QDoc es und sucht weiter, bis es das gleiche Ziel auf einer QML-Seite findet.

Ohne die Anleitung im \l-Befehl im optionalen Argument der eckigen Klammer verlinkt QDoc auf das erste passende Ziel, das es findet. QDoc kann in solchen Fällen nicht warnen, dass der Link mehrdeutig war, weil es nicht weiß, dass ein anderes passendes Ziel existiert.

Welche Argumente können in eckigen Klammern stehen?

Ein Link-Befehl mit Argumenten in eckigen Klammern hat die folgende Syntax:

\l [QML|CPP|DOC|QtModuleName] {link target} {link text}

Das Argument der eckigen Klammer ist nur im \l (link) Befehl erlaubt. Das obige Beispiel zeigt, wie QML als Argument in eckigen Klammern verwendet wird, um QDoc zu zwingen, ein QML-Ziel zu finden. Meistens wird dies ein QML-Typ sein, aber es kann auch eine QML-Mitgliedsfunktion oder eine Eigenschaft sein.

Im Beispiel brauchte QDoc kein Argument in eckigen Klammern, um die Qt C++ Namespace-Seite zu finden, da diese ohnehin das erste passende Ziel war, das QDoc fand. Um jedoch QDoc zu zwingen, ein C++-Ziel zu finden, wenn ein passendes QML-Ziel im Weg ist, kann CPP als Argument für die eckige Klammer verwendet werden. Zum Beispiel:

• \l [CPP] {Qt} {Qt C++ namespace}

...zwingt QDoc, den Qt QML-Typ zu ignorieren und die Suche fortzusetzen, bis es den Qt C++-Namensraum findet.

Wenn das Link-Ziel weder eine C++- noch eine QML-Entität ist, kann DOC als Argument für die eckige Klammer verwendet werden, um zu verhindern, dass QDoc mit einem der beiden Typen übereinstimmt. Zu diesem Zeitpunkt gab es keine Fälle von mehrdeutigen Links, in denen die Verwendung von DOC erforderlich war.

Oft weiß der Dokumentator, in welchem Qt-Modul sich das Linkziel befindet. Wenn der Modulname bekannt ist, verwenden Sie den Modulnamen als Argument für die eckige Klammer. Wenn wir im obigen Beispiel wissen, dass sich der QML-Typ namens Qt im Modul QtQml befindet, können wir den Link-Befehl wie folgt schreiben:

• \l [QtQml] {Qt} {Qt QML type}

Wenn ein Modulname als Argument für die eckige Klammer verwendet wird, sucht QDoc nur in diesem Modul nach dem Linkziel. Dies macht die Suche nach Link-Zielen effizienter.

Schließlich können die Argumente für den Modulnamen und den Entitätstyp kombiniert werden, getrennt durch ein Leerzeichen, so dass auch so etwas erlaubt ist:

• \l [CPP QtQml] {Window} {C++ class Window}

Zum Zeitpunkt der Erstellung dieses Dokuments gab es keine Fälle, in denen eine Kombination der beiden Argumente erforderlich war.

Siehe auch \sa, \target und \keyword.

\sa (siehe auch)

Der Befehl \sa definiert eine Liste von Links, die in einem separaten Abschnitt "Siehe auch" am Ende der Dokumentationseinheit angezeigt werden.

Der Befehl nimmt eine durch Komma getrennte Liste von Links als Argument. Wenn die Zeile mit einem Komma endet, können Sie die Liste in der nächsten Zeile fortsetzen. Die allgemeine Syntax lautet:

\sa {the first link}, {the second link},
    {the third link}, ...

QDoc wird automatisch versuchen, "Siehe auch"-Verknüpfungen zu erzeugen, die die verschiedenen Funktionen einer Eigenschaft miteinander verbinden. Zum Beispiel wird eine setVisible() Funktion automatisch einen Link zu visible() erhalten und umgekehrt.

Im Allgemeinen erzeugt QDoc "See also"-Verknüpfungen, die die Funktionen, die auf dieselbe Eigenschaft zugreifen, miteinander verbinden. Es erkennt vier verschiedene Syntaxversionen:

• property()
• setProperty()
• isProperty()
• hasProperty()

Der Befehl \sa unterstützt die gleiche Art von Verknüpfungen wie der Befehl \l.

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

Siehe auch \l, \target und \keyword.

\target

Der Befehl \target benennt eine Stelle in der Dokumentation, auf die Sie mit den Befehlen \l (link) und \sa (see also) verweisen können.

Der Text bis zum Zeilenumbruch wird der Zielname. Achten Sie darauf, dem Zielnamen einen Zeilenumbruch folgen zu lassen. Geschweifte Klammern sind um den Zielnamen nicht erforderlich, können aber erforderlich sein, wenn der Zielname in einem Link-Befehl verwendet wird. Siehe unten.

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

Der Zielname , der in Klammern steht, kann auf folgende Weise verknüpft werden:

• \l {capturing parentheses}

\Ziel in einer \Tabelle

Wenn Sie den Befehl \target in einer Tabelle verwenden, achten Sie darauf, dass der Befehl \target auf einen \li-Befehl(Tabellenzelle) folgt und entweder in einer separaten Zeile steht oder der letzte Inhalt der Zeile ist, in der er steht. Das liegt an der Funktionsweise des \target-Befehls: Er nimmt alles bis zum nächsten Zeilenumbruch als Parameter auf. Mit anderen Worten: Wenn Sie eine Tabelle haben und darin ein \target benötigen, stellen Sie sicher, dass es der folgenden Struktur folgt:

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

Siehe auch \l, \sa und \keyword.

\Schlüsselwort

Der Befehl \keyword benennt eine Stelle in der Dokumentation, auf die Sie mit den Befehlen \l (Link) und \sa (siehe auch) verweisen können. Er fügt außerdem das Schlüsselwort und den Ort zu generierten Indizes hinzu.

Der Befehl \keyword entspricht dem Befehl \target, mit dem Unterschied, dass der Link zu einem Schlüsselwort standardmäßig zum Anfang des QDoc-Kommentars (Thema) führt, in dem das \keyword erscheint.

Wenn Sie ein Schlüsselwort für eine Einheit section innerhalb eines Themas erstellen möchten, fügen Sie das \keyword direkt über dem Titel des Abschnitts ein:

\keyword debug
\section1 Debug command line option (--debug)
...

Im Gegensatz zu \target werden Schlüsselwörter in den Indizes der erzeugten Offline-Dokumentationsdateien (.qch) registriert. Dadurch können Benutzer die Stelle nach dem Schlüsselwort suchen, z. B. in der Indexsuche vonQt Assistant, und das Schlüsselwort ist in der Kontexthilfe von Qt Creator zugänglich.

Die Schlüsselwörter müssen für alle während des QDoc-Laufs verarbeiteten Dokumente eindeutig sein. Der Befehl verwendet den Rest der Zeile als Argument. Achten Sie darauf, dem Schlüsselwort einen Zeilenumbruch folgen zu lassen.

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

Auf die mit dem Schlüsselwort markierte Stelle kann mit verlinkt werden:

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

Wenn der Text des Schlüsselworts Leerzeichen enthält, sind die Klammern erforderlich.

Siehe auch \l (Link), \sa (siehe auch) und \target.