创建链接

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

\l (链接)

\l 链接命令用于创建指向多种不同类型目标的超链接。该命令的一般语法为：

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

……其中方括号中的link criteria 是可选的，但在link target 存在歧义时可能需要指定。请参阅下文“修复歧义链接”。

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

• 外部页面：

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

  显示效果如下：

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

  不带自定义链接文本的 URL：https://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 创建链接。

  • 使用 \keyword 的页面。
• 文档中某个锚点部分。链接目标可以是：
  • 使用以下任一“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 命令。

    由于# 字符用于文档内的链接，因此在链接到包含该字符的标题时，不能直接使用该字符。相反，必须使用反斜杠对其进行转义：

    \l {Using Qt with C\\#}

    之所以使用两个反斜杠，是因为 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 命令的主题。

  若仅希望链接中显示函数名称，可使用以下语法：\l{QWidget::}{sizeHint()} 。

• 一个示例。目标链接是示例标题或 \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 无法找到链接目标时会发出警告。

如果自动链接为某个恰好与链接目标匹配的单词生成了不需要的链接，你可以通过 `ignorewords` 配置变量来抑制它。

修复歧义链接

模棱两可的链接是指在多个 Qt 模块或文档集中都有匹配目标的链接。 例如，同一个章节标题可能出现在多个 Qt 模块中，或者一个模块中的 C++ 类名也可能是另一个模块中 QML 类型的名称。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|attached|QtModuleName] {link target} {link text}

方括号参数仅在\l (link) 命令中允许使用。上例展示了如何将QML 用作方括号参数，以强制 QDoc 匹配一个 QML 目标。 大多数情况下，这将是一个 QML 类型，但也可以是 QML 成员函数或属性。此外，某些 QML 类型包含同名的属性及附加属性。可通过attached 参数选择附加属性。如果省略attached ，系统将优先链接常规属性，而非同名的附加属性。

在示例中，QDoc 无需使用方括号参数即可找到 Qt C++ 命名空间页面，因为该页面本就是 QDoc 找到的第一个匹配目标。然而，若要强制 QDoc 在存在匹配的 QML 目标阻碍时仍查找 C++ 目标，可将CPP 作为方括号参数使用。 例如，以下链接将强制 QDoc 忽略 Qt Qml 类型，并继续搜索直至匹配到 Qt C++ 命名空间。

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

如果链接目标既不是 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 会自动尝试生成“参见”链接，将属性的各个函数相互连接起来。例如，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 {capturing parentheses}

上文中，由于目标名称包含空格，因此用方括号将其括起来。

\target 在\table

当您在表格中使用\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

\keyword 命令用于指定文档中的某个位置，您可以使用\l （链接）和\sa （另请参阅）命令链接到该位置。该命令还会将该关键字及其位置添加到生成的索引中。

\keyword 命令与 \target 命令，不同之处在于：当链接到关键字时，默认情况下链接将指向包含该\keyword 的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。