创建链接

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

\l （链接）

link 命令用于创建指向多种不同目标的超链接。该命令的一般语法是

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

......其中方括号中的link criteria 是可选的，但在link target 不明确时可能是必需的。请参阅下面的 "修复模糊链接"。

可以使用 \l 命令链接到：

• 外部页面：

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

  渲染为

  带有自定义链接文本的 URL：Qt 6 文档。

  无自定义链接文本的 URL:http://doc.qt.io/qt-6/.

  另请参见 \externalpage。

• 文档页面。链接目标可以是
  • 用\title命令指定的页面标题：

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

    渲染为

    这里是一个带有自定义链接文本的链接：QDoc - 入门。

    下面是一个链接，其链接文本与链接目标相同：QDoc 入门。

  • 用\page命令指定的页面文件名：

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

    渲染为

    创建链接"页面文章解释了如何使用 QDoc创建链接。

  • 关键字命令创建页面。
• 文档中的特定锚点部分。链接目标可以是
  • 使用Section 命令之一指定的章节标题：

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

    渲染为

    这里是指向 "编写文档 "主题中 QDoc 命令部分的链接：QDoc 命令。

    如果你在整个文档项目中都有独特的章节标题，你可以使用章节标题作为目标，而无需添加主题标题：QDoc 命令。

  • 使用\target命令定义的锚点：

    \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}.
• 一个 API 项目。目标链接可以是
  • \l QWidget - 用\class或\qmltype命令记录的类名。
  • \l QWidget::sizeHint() - 不带参数的函数签名。如果找不到不带参数的匹配函数，则使用找到的第一个匹配函数来满足链接。
  • \l QWidget::removeAction(QAction* action) - 带参数函数的签名。如果找不到完全匹配的函数，则不满足链接，QDoc 会报告 "无法链接到......"错误。
  • \l <QtGlobal> -\headerfile命令的主题。
• 一个示例。目标链接是示例标题或\example命令中使用的相对路径：

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

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

例如，如果您的文档类似于

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

对于单参数版本，大括号通常可以省略。

QDoc 还会尝试将任何与正常英文单词不相似的单词做成链接，例如 Qt 类名或函数，如QWidget 或QWidget::sizeHint() 。在这些情况下，\l 命令实际上可以省略，但通过使用该命令，可以确保 QDoc 在找不到链接目标时发出警告。此外，如果只想让函数名称出现在链接中，可以使用以下语法：

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

修复模糊链接

由于从 Qt 5.0 开始 Qt 模块化，QDoc 必须处理含混链接的可能性增加了。模棱两可的链接是指在多个 Qt 模块中都有匹配目标的链接，例如，同一个章节标题可以出现在多个 Qt 模块中，或者一个模块中的 C++ 类名也可以是另一个模块中的 QML 类型名。Qt5 中的一个真实例子就是 Qt 名称本身。Qt 既是QtCore 中一个 C++ 命名空间的名称，也是QtQml 中一个 QML 类型的名称。

假设我们要链接到Qt C++ namespace 。在 QDoc 生成此 HTML 页面时，该链接是正确的。它仍然指向 C++ 命名空间吗？Qdoc 通过这条链接命令生成了该链接：

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

现在假设我们要链接到Qt QML type 。在 QDoc 生成此 HTML 页面时，该链接也是正确的，但我们必须使用此链接命令：

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

方括号中的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 类型，但也可以是属性的 QML 成员函数。

在示例中，QDoc 不需要方括号参数来查找 Qt C++ 命名空间页面，因为该页面是 QDoc 找到的第一个匹配目标。不过，当匹配的 QML 目标受阻时，要强制 QDoc 查找 C++ 目标，CPP 可用作方括号参数。例如

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

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

如果链接目标既不是 C++ 也不是 QML 实体，DOC 可用作方括号参数，以防止 QDoc 匹配其中任何一个。在撰写本文时，还没有需要使用DOC 的模棱两可链接案例。

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

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

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

最后，模块名和实体类型参数可以组合使用，中间用空格隔开，因此也允许使用类似的参数：

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

截至本文撰写时，还没有需要将两者结合起来的情况。

另请参见 \sa、\target 和 \keyword。

\sa（另见）

\sa 命令定义了一个链接列表，这些链接将在文档单元底部的单独 "另见 "部分中呈现。

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

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

QDoc 会自动尝试生成 "See also（另见）"链接，将属性的各种功能相互连接起来。例如，setVisible() 函数将自动获得指向 visible() 的链接，反之亦然。

一般来说，QDoc 会生成 "See also "链接，将访问同一属性的函数相互连接起来。它可识别四种不同的语法版本：

• 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 命令命名文档中的一个地方，你可以使用 \l（链接）和 \sa（另见）命令链接到这个地方。

换行之前的文本将成为目标名称。请务必在目标名称后加上换行符。目标名称后不需要大括号，但在链接命令中使用目标名称时可能需要大括号。请参见下文。

/*!
    \target capturing parentheses
    \section1 Capturing Text

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

    ...
*/

括号中的目标名称可以按以下方式链接：

• \l {capturing parentheses}

\表中的目标

在表格中使用 \target 命令时，请确保 \target 命令位于\li-command （表格单元格）之后，因为某些生成器只支持针对单个单元格的目标，而不支持针对整行的目标。此外，还要确保它在单独一行，或者是所在行的最后一个内容。这是由 \target 命令的工作方式决定的；它消耗下一个换行符之前的任何内容作为参数。换句话说，如果你有一个表格，并需要在其中使用 \target 命令，请确保它遵循以下结构：

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

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

\关键字

\keyword 命令命名文档中的一个位置，您可以使用 \l（链接）和 \sa（另见）命令链接到该位置。它还会将关键字和位置添加到生成的索引中。

\keyword 命令与\target命令相似，不同之处在于当链接到一个关键词时，默认情况下链接到该关键词所在的 QDoc 注释（主题）的顶部。

如果你想在一个主题中为section 单元创建一个关键字，请在节标题的正上方添加 \keyword：

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

与 \target 不同，关键字会在生成的离线文档文件（.qch）的索引中注册。这样，用户就可以在Qt Assistant 的 "索引搜索 "中通过关键字查找位置，并在Qt Creator 的 "上下文帮助 "中访问关键字。

在 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。