Creating Links

These commands are for creating hyperlinks to classes, functions, examples, and other targets.

\l (link)

The \l link command is used to create a hyperlink to many different kinds of targets. The command's general syntax is:

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

...where the link criteria in square brackets are optional but may be required when the link target is ambiguous. See Fixing Ambiguous Links below.

You can use the \l command to link to:

• an external page:

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

  Renders as:

  An URL with a custom link text: Qt 6 Documentation.

  An URL without a custom link text: http://doc.qt.io/qt-6/.

  See also \externalpage.

• a documentation page. The link target can be:
  • the page title specified with the \title command:

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

    Renders as:

    Here is a link with a custom link text: QDoc - Getting Started.

    Here is a link with a link text that is the same as link target: Getting Started with QDoc.

  • the page file name specified with the \page command:

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

    Renders as:

    The Creating Links page article explains how to create links with QDoc.

  • the page with a \keyword command.
• a particular anchor section within a document. The link target can be:
  • a section title specified with one of the Section commands:

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

    Renders as:

    Here is a link to a QDoc Commands section of the Writing Documentation topic: 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: QDoc Commands.

  • an anchor defined with a \target command:

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

• an API item. Target links can be:
  • \l QWidget - The name of a class documented with the \class or \qmltype command.
  • \l QWidget::sizeHint() - The signature of a function without parameters. If a matching function without parameters can't be found, the link is satisfied with the first matching function found.
  • \l QWidget::removeAction(QAction* action) - The signature of a function with parameters. If an exact match is not found, the link is not satisfied and QDoc reports a Can't link to... error.
  • \l <QtGlobal> - The subject of a \headerfile command.
• an example. The target link is the example title or a relative path used in an \example command:

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

If the link target is equivalent to the link text, you can omit the second argument.

For example, if you have documentation like:

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

You can simplify this as follows:

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

For the one-parameter version, the braces can often be omitted.

QDoc also tries to make a link out of any word that doesn't resemble a normal English word, for example, Qt class names or functions, like QWidget or QWidget::sizeHint(). In these cases, the \l command can actually be omitted, but by using the command, you ensure that QDoc will emit a warning if it cannot find the link target. In addition, if you only want the function name to appear in the link, you can use the following syntax:

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

Fixing Ambiguous Links

Because of the modularization of Qt beginning with Qt 5.0, The possibility that QDoc will have to deal with ambiguous links has increased. An ambiguous link is one that has a matching target in more than one Qt module, for example, the same section title can appear in more than one Qt module, or the name of a C++ class in one module can also be the name of a QML type in another module. A real example in Qt5 is the name Qt itself. Qt is the name of both a C++ namespace in QtCore and a QML type in QtQml.

Suppose we want to link to the Qt C++ namespace. At the time QDoc generated this HTML page, that link was correct. Does it still go to the C++ namespace? Qdoc generated that link from this link command:

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

Now suppose we want to link to the Qt QML type. At the time QDoc generated this HTML page, that link was also correct, but we had to use this link command:

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

The QML in square brackets tells QDoc to accept a matching target only if the target is on a QML page. Qdoc actually finds the C++ namespace target first, but since that target is on a C++ page, QDoc ignores it and keeps looking until it finds the same target on a QML page.

Without the guidance in the \l command in the optional square bracket argument, QDoc links to the first matching target it finds. QDoc can't warn that the link was ambiguous in such cases because it doesn't know that another matching target exists.

What arguments can appear in square brackets?

A link command with square bracket argument has the following syntax:

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

The square bracket argument is only allowed in the \l (link) command. The example above shows how QML is used as the square brackets argument to force QDoc to match a QML target. Most often, this will be a QML type, but it can also be a QML member function of property.

In the example, QDoc didn't need a square bracket argument to find the Qt C++ namespace page, because that one was the first matching target QDoc found anyway. However, to force QDoc to find a C++ target when a matching QML target gets in the way, CPP can be used as the square bracket argument. For example:

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

...will force QDoc to ignore the Qt QML type and continue searching until it matches the Qt C++ namespace.

If the link target is neither a C++ nor a QML entity, DOC can be used as the square bracket argument to prevent QDoc from matching either of those. At this writing, there were no cases of ambiguous links where using DOC was required.

Often, the documentor knows which Qt module the link target is in. When the module name is known, use the module name as the square bracket argument. In the example above, if we know that the QML type named Qt is located in the QtQml module, we can write the link command like this:

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

When a module name is used as the square bracket argument, QDoc will search for the link target in that module only. This makes searching for link targets more efficient.

Finally, the module name and entity type arguments can be combined, separated by a blank, so something like this is also allowed:

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

As of this writing, there were no cases where combining the two was required.

See also \sa, \target, and \keyword.

\sa (see also)

The \sa command defines a list of links that will be rendered in a separate "See also" section at the bottom of the documentation unit.

The command takes a comma-separated list of links as its argument. If the line ends with a comma, you can continue the list on the next line. The general syntax is:

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

QDoc will automatically try to generate "See also" links interconnecting a property's various functions. For example, a setVisible() function will automatically get a link to visible() and vice versa.

In general, QDoc will generate "See also" links that interconnect the functions that access the same property. It recognizes four different syntax versions:

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

The \sa command supports the same kind of links as the \l command.

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

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

See also \l, \target and \keyword.

\target

The \target command names a place in the documentation that you can link to using the \l (link) and \sa (see also) commands.

The text up to the line break becomes the target name. Be sure to follow the target name with a line break. Curly brackets are not required around the target name, but they may be required when the target name is used in a link command. See below.

/*!
    \target capturing parentheses
    \section1 Capturing Text

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

    ...
*/

The target name capturing parentheses can be linked to in the following way:

• \l {capturing parentheses}

\target in a \table

When you use the \target command in a table, make sure that the \target command follows a \li-command (table cell), and that it's either on a separate line, or the last content that occurs in the line it's in. This is due to how the \target command works; it consumes anything up to the next line break as its parameter. In other words, if you have a table and need a \target within it, make sure that it follows the following structure:

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

See also \l, \sa and \keyword.

\keyword

The \keyword command names a place in the documentation that you can link to using the \l (link) and \sa (see also) commands. It also adds the keyword and the location to generated indices.

The \keyword command is like the \target command, except that when linking to a keyword, by default the link goes to the top of the QDoc comment (topic) the \keyword appears in.

If you want to create a keyword for a section unit within a topic, add the \keyword directly above the section title:

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

Unlike \target, keywords are registered in indices of generated offline documentation files (.qch). This allows users to look up the location by keyword, for instance, in Qt Assistant's Index Search, and makes the keyword accessible in Qt Creator's context help.

Keywords must be unique over all the documents processed during the QDoc run. The command uses the rest of the line as its argument. Be sure to follow the keyword with a line break.

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

    ...
*/

The location marked with the keyword can be linked to with:

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

If the keyword text contains spaces, the brackets are required.

See also \l (link), \sa (see also) and \target.