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, jedoch erforderlich sein können, wenn der „ link target “ mehrdeutig ist. Siehe „Behebung mehrdeutiger Links“ weiter unten.

Mit dem Befehl „ \l “ kannst du Links erstellen zu:

• eine externe Seite:

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

  Wird wie folgt dargestellt:

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

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

  Siehe auch \externalpage.

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

    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 dargestellt als:

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

    Hier ist ein Link, dessen Linktext mit dem Linkziel übereinstimmt: Erste Schritte mit QDoc.

  • Der Dateiname der Seite, der 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.

    wird wie folgt dargestellt:

    Der Artikel auf der Seite „Links erstellen“ erklärt, wie man mit QDoc Links erstellt.

  • die Seite mit einem \keyword Befehl.
• einem bestimmten Ankerabschnitt innerhalb eines Dokuments. Das Ziel des Links kann sein:
  • ein Abschnittstitel, der mit einem der Abschnitt-Befehle 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}.

    Wird dargestellt als:

    Hier ist ein Link zum Abschnitt „QDoc-Befehle“ des Themas „Dokumentation schreiben“: QDoc-Befehle.

    Wenn Sie in Ihrem Dokumentationsprojekt eindeutige Abschnittsüberschriften verwenden, können Sie die Abschnittsüberschrift als Ziel verwenden, ohne den Thema-Titel hinzufügen zu müssen: QDoc-Befehle.

    Da das Zeichen „ # “ für Verlinkungen innerhalb von Dokumenten verwendet wird, kann es bei Verweisen auf Titel, die dieses Zeichen enthalten, nicht wörtlich übernommen werden. Stattdessen muss es mit einem Backslash maskiert werden:

    \l {Using Qt with C\\#}

    Es werden zwei Backslashes verwendet, da QDoc den Text verarbeitet, bevor er an den Link-Befehl übergeben wird.

  • ein mit dem \target Befehl:

    \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}.

• einem API-Element. Ziel-Links können sein:
  • \l QWidget - Der Name einer Klasse, die mit dem \class oder \qmltype Befehl dokumentiert wurde.
  • \l QWidget::sizeHint() - Die Signatur einer Funktion ohne Parameter. Kann keine passende Funktion ohne Parameter gefunden werden, gilt der Verweis als erfüllt, sobald die erste passende Funktion gefunden wird.
  • \l QWidget::removeAction(QAction* action) - Die Signatur einer Funktion mit Parametern. Wird keine exakte Übereinstimmung gefunden, wird der Verweis nicht hergestellt und QDoc meldet den Fehler „Can't link to... “.
  • \l <QtGlobal> - Das Subjekt eines \headerfile Befehls.

  Wenn Sie möchten, dass im Link nur der Funktionsname erscheint, können Sie die folgende Syntax verwenden: „ \l{QWidget::}{sizeHint()} “.

• Ein Beispiel. Das Linkziel ist der Titel des Beispiels 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.

Beispielsweise, 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}.
*/

können Sie 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.

Automatische Verknüpfung

QDoc versucht außerdem, aus jedem Wort, das nicht wie ein normales englisches Wort aussieht, einen Link zu erstellen, beispielsweise aus Qt-Klassennamen oder -Funktionen wie „ QWidget “ oder „ QWidget::sizeHint()“. In diesen Fällen kann der Befehl „ \l “ zwar weggelassen werden, doch durch die Verwendung des Befehls stellen Sie sicher, dass QDoc eine Warnung ausgibt, falls es das Linkziel nicht finden kann.

Wenn die automatische Verlinkung einen unerwünschten Link für ein Wort erzeugt, das zufällig mit einem Linkziel übereinstimmt, können Sie diesen mit der Konfigurationsvariable `ignorewords ` unterdrücken.

Behebung mehrdeutiger Verknüpfungen

Ein mehrdeutiger Link ist ein Link, dessen Ziel in mehr als einem Qt-Modul oder Dokumentationssatz vorkommt. Beispielsweise kann derselbe Abschnittstitel in mehr als einem Qt-Modul vorkommen, oder der Name einer C++-Klasse in einem Modul kann gleichzeitig der Name eines QML-Typs in einem anderen Modul sein. Ein konkretes Beispiel in Qt ist der Name „Qt“ selbst: Er ist sowohl der Name eines C++-Namensraums in QtCore als auch der Name eines QML-Typs in QtQml.

Angenommen, wir möchten einen Link zu Qt C++ namespace setzen. Zum Zeitpunkt der Erstellung dieser HTML-Seite durch QDoc war dieser Link korrekt. Führt er immer noch zum C++-Namespace? QDoc hat diesen Link anhand des folgenden Link-Befehls generiert:

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

Nehmen wir nun an, wir möchten einen Link zu Qt QML type erstellen. Zu dem Zeitpunkt, als QDoc diese HTML-Seite generierte, war dieser Link ebenfalls korrekt, aber wir mussten diesen Link-Befehl verwenden:

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

Der QML-Befehl in eckigen Klammern weist QDoc an, ein passendes Ziel nur dann zu akzeptieren, wenn sich dieses auf einer QML-Seite befindet. QDoc findet zwar zunächst das Ziel im C++-Namespace, da sich dieses jedoch auf einer C++-Seite befindet, ignoriert QDoc es und sucht weiter, bis es dasselbe Ziel auf einer QML-Seite findet.

Ohne die Vorgabe im Befehl „\l “ im optionalen Argument in eckigen Klammern verlinkt QDoc auf das erste passende Ziel, das es findet. QDoc kann in solchen Fällen nicht warnen, dass der Link mehrdeutig war, da es nicht weiß, dass ein weiteres passendes Ziel existiert.

Welche Argumente können in eckigen Klammern stehen?

Ein Verknüpfungsbefehl mit einem Argument in eckigen Klammern hat folgende Syntax:

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

Das Argument in eckigen Klammern ist nur im Befehl „ \l (link) “ zulässig. Das obige Beispiel zeigt, wie „ QML “ als Argument in eckigen Klammern verwendet wird, um QDoc zu zwingen, ein QML-Ziel abzugleichen. Meistens handelt es sich dabei um einen QML-Typ, es kann sich jedoch auch um eine QML-Memberfunktion oder -Eigenschaft handeln. Darüber hinaus enthalten einige QML-Typen Eigenschaften und angehängte Eigenschaften mit demselben Namen. Angehängte Eigenschaften können mit einem „ attached “-Argument ausgewählt werden. Wird „ attached “ weggelassen, werden reguläre Eigenschaften gegenüber angehängten Eigenschaften mit doppelten Namen bevorzugt verknüpft.

Im Beispiel benötigte QDoc kein Argument in eckigen Klammern, um die Seite des Qt-C++-Namespace zu finden, da diese ohnehin das erste passende Ziel war, das QDoc gefunden hat. Um QDoc jedoch zu zwingen, ein C++-Ziel zu finden, wenn ein passendes QML-Ziel im Weg steht, kann „ CPP “ als Argument in eckigen Klammern verwendet werden. Beispielsweise zwingt der folgende Link QDoc dazu, den Qt Qml-Typ zu ignorieren und die Suche fortzusetzen, bis eine Übereinstimmung mit dem Qt-C++-Namensraum gefunden wird.

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

Ist das Linkziel weder eine C++- noch eine QML-Entität, kann „ DOC “ als Argument in eckigen Klammern verwendet werden, um zu verhindern, dass QDoc eine Übereinstimmung mit einer dieser beiden Entitäten herstellt. Zum Zeitpunkt der Erstellung dieses Artikels gab es keine Fälle von mehrdeutigen Links, bei denen die Verwendung von „ DOC “ erforderlich war.

Häufig weiß der Dokumentierer, in welchem Qt-Modul sich das Linkziel befindet. Wenn der Modulname bekannt ist, verwenden Sie den Modulnamen als Argument in eckigen Klammern. 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}

Wird ein Modulname als Argument in eckigen Klammern verwendet, sucht QDoc ausschließlich in diesem Modul nach dem Verknüpfungsziel. Dies macht die Suche nach Verknüpfungszielen effizienter.

Schließlich können die Argumente für den Modulnamen und den Entitätstyp durch ein Leerzeichen getrennt kombiniert werden, sodass auch eine Schreibweise wie die folgende zulässig ist:

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

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

Siehe auch \sa, \target, sowie \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 erwartet als Argument eine durch Kommas getrennte Liste von Links. Endet die Zeile mit einem Komma, 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 versucht automatisch, „Siehe auch“-Links zu generieren, die die verschiedenen Funktionen einer Eigenschaft miteinander verknüpfen. Beispielsweise erhält die Funktion `setVisible()` automatisch einen Link zu `visible()` und umgekehrt.

Im Allgemeinen generiert QDoc „Siehe auch“-Links, die die Funktionen miteinander verbinden, die auf dieselbe Eigenschaft zugreifen. Es erkennt vier verschiedene Syntaxvarianten:

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

Der Befehl „ \sa “ unterstützt dieselbe Art von Verknüpfungen wie der \l Befehl.

/*!
    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 “ (siehe auch) verweisen können.

Der Text bis zum Zeilenumbruch wird zum Zielnamen. Achten Sie darauf, dass auf den Zielnamen ein Zeilenumbruch folgt. Geschweifte Klammern um den Zielnamen sind nicht erforderlich, können jedoch notwendig 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.

    ...
*/

Die Klammern, die den Zielnamen umschließen, können wie folgt verlinkt werden:

• \l {capturing parentheses}

Oben ist der Zielname in eckige Klammern gesetzt, da er Leerzeichen enthält.

\target in einem \table

Wenn Sie den Befehl „ \target “ in einer Tabelle verwenden, stellen Sie sicher, dass der Befehl „ \target “ auf einen \liBefehl (Tabellenzelle) folgt, da einige Generatoren nur Ziele für einzelne Zellen und nicht für ganze Zeilen unterstützen. Stellen Sie außerdem sicher, dass er entweder in einer separaten Zeile steht oder der letzte Inhalt in der Zeile ist, in der er vorkommt. Dies liegt an der Funktionsweise des Befehls „ \target “; er verwendet alles bis zum nächsten Zeilenumbruch als Parameter. Mit anderen Worten: Wenn Sie eine Tabelle haben und darin einen „ \target “-Befehl benötigen, stellen Sie sicher, dass dieser der folgenden Struktur entspricht:

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

Siehe auch \l, \sa und \keyword.

\keyword

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

Der Befehl „ \keyword “ ähnelt dem \target Befehl, mit dem Unterschied, dass beim Verlinken auf ein Schlüsselwort der Link standardmäßig an den Anfang des QDoc-Kommentars (Themas) führt, in dem „ \keyword “ vorkommt.

Wenn Sie ein Schlüsselwort für eine „ section “-Einheit innerhalb eines Themas erstellen möchten, fügen Sie den Befehl „ \keyword “ direkt über dem Abschnittstitel ein:

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

Im Gegensatz zu „ \target “ werden Schlüsselwörter in den Indizes der generierten Offline-Dokumentationsdateien (.qch) registriert. Dadurch können Benutzer den Speicherort beispielsweise über die Indexsuche von „Qt Assistant “ anhand des Schlüsselworts nachschlagen, und das Schlüsselwort ist in der Kontexthilfe von „ Qt Creator “ verfügbar.

Schlüsselwörter müssen über alle während des QDoc-Laufs verarbeiteten Dokumente hinweg eindeutig sein. Der Befehl verwendet den Rest der Zeile als Argument. Achten Sie darauf, dass auf das Schlüsselwort ein Zeilenumbruch folgt.

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

    ...
*/

Die mit dem Schlüsselwort markierte Stelle kann wie folgt 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.