包含外部代码

以下命令可让你包含来自外部文件的代码片段。你可以让 QDoc 包含文件的完整内容，或者你可以引用文件的部分并跳过其他部分。后者的典型用法是逐块引用文件。

注意： 虽然所有这些命令都可以用来渲染 C++ 代码，但 `\snippet` 和 `\codeline` 命令比其他命令更受欢迎。这些命令允许用其他 Qt 语言绑定的等效代码片段替换文档中的 C++ 代码片段。

\quotefile

\quotefile 命令扩展为所给参数文件的完整内容。

该命令将行中剩余的部分视为其参数的一部分，确保在文件名后跟一个换行符。

文件的文案以单独的段落渲染，使用等距字体和标准缩进。代码按原样显示。

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

另请参阅 \quotefromfile 和 \code。

\quotefromfile

\quotefromfile 命令用于打开所给参数文件进行引用。

该命令将行中剩余的部分视为其参数的一部分，确保在文件名后跟一个换行符。

该命令用于引用文件的部分，使用遍历命令： \printline、\printto、\printuntil、\skipline、\skipto、\skipuntil。这使得你可以引用文件的一部分。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc 记录了它所引用的文件和该文件中的当前位置（有关更多信息，请参阅 \printline）。不需要“关闭”文件。

另请参阅 \quotefile、\code 和 \dots。

\printline

\printline 命令扩展为当前源文件中从当前位置到下一个非空白行的行。

为了确保文档与源文件保持同步，必须在命令中指定行的子串作为参数。请注意，命令将行中剩余的部分视为其参数的一部分，确保在子串后跟一个换行符。

源文件的行以单独的段落形式呈现，使用等宽字体和标准缩进。代码以纯文本形式显示。

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc按顺序读取文件。要前进当前位置，可以使用\skip...中的任意一个命令。要后退当前位置，可以使用\quotefromfile命令。

如果子字符串参数被斜杠包围，它被解释为正则表达式。

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(完整的示例文件...)

正则表达式/^\}/使得QDoc打印到当前行开头且不缩进的第一处'<'字符。/.../包含正则表达式，'<'字符代表行的开头。'}'字符必须转义，因为它在正则表达式中是一个特殊字符。

如果指定的子字符串或正则表达式无法找到，即如果源代码已更改，QDoc将发出警告。

请参阅\printto和\printuntil。

\printto

\printto命令展开为从当前位置到最后一条包含给定子字符串的下一行的所有行，但不包括该行。

该命令将行的其余部分视为其参数的一部分，确保在子字符串后跟一个换行符。该命令还遵循与\printline命令相同的定位和参数约定。

源文件中的行以单独的段落形式呈现，使用等宽字体和标准缩进。代码以纯文本形式显示。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

请参阅\printline和\printuntil。

\printuntil

\printuntil命令扩展为从当前位置到最后一条包含给定子字符串的行的所有行，包括该行。

该命令将行的其余部分视为其参数的一部分，确保在子字符串后跟一个换行符。该命令还遵循与\printline命令相同的定位和参数约定。

如果没有使用参数使用\printuntil，它将扩展为从当前位置到引用文件的结尾的所有行。

源文件中的行以单独的段落形式呈现，使用等宽字体和标准缩进。代码以纯文本形式显示。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

请参阅\printline和\printto。

\skipline

\skipline命令忽略当前源文件中的下一行（非空白行）。

Doc按顺序读取文件，\skipline命令用于移动当前位置（忽略源代码的某一行）。请参阅上面关于文件定位的说明。

该命令将行的其余部分视为其参数的一部分，确保在子字符串后跟一个换行符。该命令还遵循与参数相同的约定，如\printline命令，并且与\quotefromfile命令结合使用。

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

请参阅\skipto、\skipuntil和\...。

\skipto

\skipto命令忽略当前位置到包含给定子字符串的下一行的所有行，但不包括该行。

QDoc按照顺序读取文件，并使用\skipto命令来移动当前位置（忽略若干行源文件中的行）。请参阅上述关于文件定位的说明。

该命令将当前行的其余部分视为其参数的一部分，确保紧跟子字符串后有一个换行。

该命令还遵循与参数相同的\printline命令约定，并与\quotefromfile命令一起使用。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

另请参阅\skipline、\skipuntil和\dots。

\skipuntil

\skipuntil命令忽略从当前位置到指定的子字符串所在的下一行（包括该行）的所有行。

QDoc按照顺序读取文件，并使用\skipuntil命令来移动当前位置（忽略若干行源文件中的行）。请参阅上述关于文件定位的说明。

该命令将当前行的其余部分视为其参数的一部分，确保紧跟子字符串后有一个换行。

该命令还遵循与参数相同的\printline命令约定，并与\quotefromfile命令一起使用。

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

另请参阅\skipline、\skipto和\dots。

\dots

\dots命令表示在引用文件时省略了源文件的部分内容。

该命令与\quotefromfile命令一起使用，并且应该独占一行。点号采用新行格式，并使用等宽字体。

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

默认缩进为4个空格，但可以使用命令的可选参数进行调整。

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

另请参阅\skipline、\skipto和\skipuntil。

\snippet

\snippet命令导致包括一个代码片段，作为预格式化的文本以原始文本方式显示，可以进行语法高亮。

每个代码片段通过包含它的文件和该文件的唯一标识符进行引用。代码片段文件通常存储在文档目录内的snippets目录中（例如，$QTDIR/doc/src/snippets）。

例如，以下文档引用了位于文档目录子目录中的文件中的一个片段

\snippet snippets/textdocument-resources/main.cpp Adding a resource

文件名之后的文本是该片段的唯一标识符。这用于在相关片段文件中对引用的代码进行分隔，如下面与上述\snippet命令相对应的例子所示

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

默认情况下，QDoc将//!作为代码片段标记查找。对于.pro、.py、.cmake和CMakeLists.txt文件，检测到#!。最后，在.html、.qrc、.ui、.xml和.xq文件中接受<!--。

\codeline

\codeline命令插入一个空白的预格式化文本行。它用于在片段之间插入间隔，而无需关闭当前的预格式化文本区并打开一个新区域。

在行内插入代码创建链接