创建链接

这些命令用于创建到类、函数、示例和其他目标的超链接。

\l (链接)

\l 链接命令用于创建到许多不同目标的超链接。该命令的一般语法是

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

...其中方括号内的 链接条件 是可选的，但在 链接目标 不明确时可能是必需的。请参阅下面的 修复模糊链接。

以下是一个使用 \l 命令将链接到外部页面的示例

/*!
  Read the \l {https://doc.qt.ac.cn/qt-6/}
  {Qt 6 Documentation} carefully.
*/

如果链接目标是与链接文本等效，则可以省略第二个参数。

例如，如果您有如下文档

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

您可以简化如下

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

对于单参数版本，大括号通常可以省略。\l 命令支持几种链接方式

• \l QWidget - 使用 \class 命令记录的类的名称。
• \l QWidget::sizeHint() - 无参数的函数签名。如果找不到匹配的无参数函数，则链接将满足找到的第一个匹配函数。
• \l QWidget::removeAction(QAction* action) - 带参数的函数签名。如果找不到完全匹配的，则链接不会满足，QDoc 会报告 无法链接到... 错误。
• \l <QtGlobal> - 使用 \headerfile 命令的主题。
• \l widgets/wiggly - 在 \example 命令中使用的相对路径。
• \l {QWidget Class Reference} - 使用 \title 命令的标题。
• \l {Introduction to QDoc} - 章节命令 中的文本。
• \l fontmatching - 使用 \target 命令的参数。
• \l {共享类} - 在 \keyword 命令中命名的关键字。
• \l http://qt-project.org/ - URL。

QDoc 还会尝试将任何看起来不像正常英文单词的单词变成链接，例如，Qt 类名或函数，比如 QWidget 或 QWidget::sizeHint()。在这些情况下，可以省略 \l 命令，但使用该命令可以确保如果 QDoc 找不到链接目标，它将发出警告。此外，如果您只想在链接中显示函数名，可以使用以下语法

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

修复模糊链接

由于Qt从Qt 5.0开始模块化，QDoc必须处理模糊链接的可能性已经增加。一个模糊链接是在多个Qt模块中有一个匹配的目标，例如，相同的章节标题可以出现在多个Qt模块中，或者一个模块中C++类的名称也可以是另一个模块中QML类型的名称。Qt 5中的一个真实示例就是Qt本身这个名字。Qt是QtCore模块中的C++命名空间和QtQml模块中的QML类型的名称。

假设我们想链接到Qt C++命名空间。当QDoc生成这个HTML页面时，这个链接是正确的。它现在仍然会链接到C++命名空间吗？QDoc从这个链接命令生成这个链接

• \l {Qt} {Qt C++命名空间}

现在假设我们想链接到Qt QML类型。当QDoc生成这个HTML页面时，这个链接也是正确的，但我们必须使用这个链接命令

• \l [QML] {Qt} {Qt QML类型}

方括号中的QML告诉QDoc只在目标位于QML页面时才接受匹配的目标。QDoc实际上首先找到C++命名空间的目标，但由于该目标位于C++页面，QDoc会忽略它并继续查找，直到它在QML页面中找到相同的目标。

如果没有在可选的方括号参数中的\l命令中的引导，QDoc会链接到它找到的第一个匹配目标。在这样情况下，QDoc无法警告链接是模糊的，因为它不知道存在另一个匹配的目标。

方括号中可以出现哪些参数?

具有方括号参数的链接命令具有以下语法

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

方括号参数仅在\l (link)命令中允许使用。上面的例子显示了如何将QML用作方括号参数，强制QDoc匹配一个QML目标。大多数情况下，这将是QML类型，但它也可以是属性成员函数。

在示例中，不需要方括号参数来查找Qt C++命名空间页面，因为QDoc无论如何都会找到第一个匹配的目标。但是，为了强制QDoc在匹配到QML目标时找到C++目标，可以使用代码CPP作为方括号参数。例如

• \l [CPP] {Qt} {Qt C++命名空间}

...将强制QDoc忽略Qt QML类型，并继续搜索，直到它匹配Qt C++命名空间。

如果链接目标是既不是C++也不是QML实体，那么可以将DOC用作方括号参数以防止QDoc匹配这些目标。就写作本文时，没有使用DOC的需求的模糊链接案例。

通常，文档编写者知道链接目标是哪个Qt模块。当模块名称已知时，将模块名称用作方括号参数。在上面的例子中，如果我们知道名为Qt的QML类型位于QtQml模块中，我们可以这样编写链接命令

• \l [QtQml] {Qt} {Qt QML类型}

当使用模块名称作为方括号参数时，QDoc将只在该模块中搜索链接目标。这使得搜索链接目标更加高效。

最后，可以组合模块名称和实体类型参数，用空格隔开，因此也可以允许这样的内容

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

据本文写作时，没有需要组合这两个参数的情况。

另请参阅 \sa、\target 以及 \keyword。

\sa (also see)

\sa 命令定义了一组链接，将在文档单元底部单独的“另请参阅”部分中渲染。

命令接受以逗号分隔的链接列表作为其参数。如果行以逗号结尾，则可以在下一行继续列表。一般语法是

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

QDoc 将自动尝试生成“另请参阅”链接，以连接属性的各种函数。例如，setVisible() 函数将自动获取对 visible() 的链接，反之亦然。

一般情况下，QDoc 将生成连接访问相同属性的函数的“另请参阅”链接。它识别四种不同的语法版本

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

\sa 命令支持的链接与学生命令\l相同。

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

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

另请参阅 \l、\target 和 \keyword。

\target

\target 命令命名了文档中的一个位置，可以使用\l (链接) 和 \sa (另请参阅) 命令链接到该位置。

文本直到换行符将成为目标名称。请确保跟随目标名称后有一个换行符。无需在目标名称周围使用花括号，但在使用链接命令中的目标名称时可能需要。请参阅以下内容。

/*!
    \target capturing parentheses
    \section1 Capturing Text

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

    ...
*/

目标名称 捕获圆括号 可以通过以下方式进行链接

• \l {捕获圆括号}

\target 在 \table

当在表格中使用 \target 命令时，请确保 \target 命令后面紧跟着 \li-command (表格单元格)，并且它在单独的一行上，或者在它所在的行中最后出现的内文。这是由于 \target 命令的工作方式；它 consumes 任何直到下一个换行符作为它的参数。换句话说，如果您有一个表格并在其中需要 \target，请确保它遵循以下结构

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

另请参阅 \l、\sa 和 \keyword。

\keyword

\keyword 命名了文档中的一个位置，您可以使用 \l (链接) 和 \sa (另请参阅) 命令在该位置链接。

\keyword 命令类似于 \target 命令，除了当链接到关键字时，链接会转到 \keyword 出现的 QRDoc 注释的顶部。如果您想在 \page 内部的编码部分创建链接目标，请使用 \target。关键字可以从任何地方使用简单语法进行链接。

关键字必须在 QDoc 运行期间处理的整个文档中是唯一的。该命令使用行的其余部分作为其参数。请确保在关键字后面跟随一个换行符。

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

    ...
*/

使用关键词标记的位置可以与以下内容链接：

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

如果关键词文本包含空格，则需要使用括号。

另请参阅 \l (链接)，\sa (参见) 和 \target。