文本标记
文本格式化命令用于指定文本的呈现方式。
\a (参数标记)
\a 命令会告知QDoc，接下来的单词是一个形式参数名。
当形式参数未被文档化或拼写错误时，系统会发出警告，因此，在编写函数文档时，应在函数描述中按名称逐一列出每个形式参数，并在每个参数名称前添加\a 命令。这样，参数名称就会以斜体显示。
形式参数名可以使用大括号括起来，但这不是必需的。
\c (代码字体)
\c 命令用于将变量名、用户定义的类名以及C++关键字（例如int 和for ）以代码字体显示。
该命令使用等宽字体渲染其参数。如果要以代码字体渲染的文本中包含空格，请将整个文本用大括号括起来：
\c 命令在其参数中接受特殊字符\ ，该字符会被渲染为普通字符。因此，若要使用嵌套命令，必须改用teletype（\tt ）命令。
\details (可折叠)
\details 和\enddetails 命令会生成一个可折叠的 <details> 元素，并通过 <summary> 来控制其隐藏/显示状态。
在生成 HTML 输出时，请使用\details 和\enddetails 命令来生成可折叠的<details> HTML 元素。该命令接受一个用大括号括起的可选摘要字符串。此可选参数用于指定详细信息的可见标题。
如果省略该参数，QDoc 将输出“...”作为摘要字符串。
例如，给定以下输入：
/*!
\details {QDoc details}
\note You're looking at detailed information.
\enddetails
*/如果 QDoc 正在生成 HTML，它会将这些命令转换为：
<details>
<summary>QDoc details</summary>
<div class="admonition note">
<p><b>Note: </b>You're looking at detailed information.</p>
</div>
</details>QDoc 将其渲染为：
QDoc 详细信息
注意：您正在 查看详细信息。
对于其他任何输出格式，QDoc 会将内容生成一个普通段落，忽略摘要字符串。该命令于 Qt 6.6 版本中引入 QDoc。
\div
\div 和\enddiv 命令用于界定一个较大或较小的文本块（其中可能包含其他QDoc命令），并为其应用特殊的格式化属性。
必须在花括号中提供一个参数，如下所示的 QDoc 注释中所示。该参数不会被解释，而是作为 QDoc 输出的标签的属性使用。
例如，我们可能希望渲染一张内联图片，使其浮动在当前文本块的右侧：
/*!
\div {class="float-right"}
\inlineimage qml-column.png
\enddiv
*/如果 QDoc 正在生成 HTML，它会将这些命令转换为：
<div class="float-right"><p><img src="images/qml-column.png" /></p></div>对于 HTML，属性值float-right将引用 style.css 文件中的一个规则，在此情况下可能是：
div.float-right
{
float: right; margin-left: 2em
}注意：请注意 ， \div 命令可以嵌套使用。
下面是一个示例，摘自用于为 Qt 4.7 生成 index.html 的 index.qdoc 文件：
\div {class="indexbox guide"}
\div {class="heading"}
Qt Developer Guide
\enddiv
\div {class="indexboxcont indexboxbar"}
\div {class="section indexIcon"} \emptyspan
\enddiv
\div {class="section"}
Qt is a cross-platform application and UI
framework. Using Qt, you can write web-enabled
applications once and deploy them across desktop,
mobile and embedded operating systems without
rewriting the source code.
\enddiv
\div {class="section sectionlist"}
\list
\li \l{Getting Started}
\li \l{Installation} {Installation}
\li \l{how-to-learn-qt.html} {How to learn Qt}
\li \l{tutorials.html} {Tutorials}
\li \l{Qt Examples} {Examples}
\li \l{qt4-7-intro.html} {What's new in Qt 4.7}
\endlist
\enddiv
\enddiv
\enddiv
当所有 class 属性的值都按照用于渲染 Qt 文档的 style.css 文件中的定义进行设置时，上述示例的渲染效果如下：
Qt 开发者指南
另请参阅 \span.
\span
\span 命令可对一小段文本应用特殊格式。
必须提供两个参数，每个参数都用花括号括起来，如下面的 QDoc 注释所示。第一个参数不会被解释，但用于指定 QDoc 输出的标签的格式化属性。第二个参数是需要应用特殊格式化属性进行渲染的文本。
例如，我们可能希望将数字列表中每个项目的第一个单词渲染为蓝色。
/*!
Global variables with complex types:
\list 1
\li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
\li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
\li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
\li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
\endlist
*/类variableName指代您 style.css 文件中的一个子句。
.variableName
{
font-family: courier;
color: blue
}使用上文所示的variableName子句，该示例的渲染效果如下：
具有复杂类型的全局变量：
- globals.cpp 第 14 行中的mutableComplex1
- globals.cpp 第 15 行中的mutableComplex2
- globals.cpp 第 16 行中的constComplex1
- globals.cpp 文件第 17 行中的constComplex2
注意： span命令不会导致开始一个新段落。
另请参阅 \div。
\tm (商标)
\tm 命令表示其参数是一个商标。QDoc在生成页面时，会在该参数首次出现的位置后添加商标符号 `™`。
在项目配置中，navigation.trademarkspage 变量用于定义包含商标相关文档的页面标题。
navigation.trademarkspage = Trademarks如果设置了该变量，商标符号的每次出现都会链接到商标页面。
注意：在 章节标题中 ，\tm 命令将被忽略，其参数将按原样显示。
另请参阅 \section1 以及 navigation。
\tt (电传打字机字体)
\tt 命令会将其参数以等宽字体显示。该命令的行为与 \c 命令的行为完全相同，不同之处在于\tt 允许你在参数中嵌套QDoc命令（例如 \e, \b 和 \underline）。
/*!
After having populated the main container with
child widgets, \c setupUi() scans the main container's list of
slots for names with the form
\tt{on_\e{objectName}_\e{signalName}().}
*/如果要在代码字体中渲染的文本中包含空格，请将整个文本用大括号括起来。
另请参阅 \c。
\b
\b 命令会将其参数以粗体显示。该命令以前称为\bold 。
/*!
This is regular text; \b {this text is
rendered using the \\b command}.
*/\br
\br 命令会强制换行。
\e （强调、斜体）
\e 命令会将其参数以特殊字体显示，通常为斜体。该命令以前称为\i ，现已弃用。
如果参数中包含空格或其他标点符号，请将参数用大括号括起来。
/*!
Here, we render \e {a few words} in italics.
*/若要在包含空格的参数中使用其他 QDoc 命令，则必须始终将该参数用大括号括起来。但 QDoc 足够智能，能够识别圆括号，因此在这种情况下无需使用大括号：
/*!
An argument can sometimes contain whitespaces,
for example: \e QPushButton(tr("A Brand New Button"))
*/最后，参数末尾的标点符号不包含在参数中，'s' 也不包含在内。
\sub
\sub 命令会将其参数显示在常规文本基线之下，并使用较小的字体。
/*!
Definition (Range): Consider the sequence
{x\sub n}\sub {n > 1} . The set
{x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
is called the range of the sequence.
*/如果参数中包含空格或其他标点符号，请将参数用大括号括起来。
\sup
\sup 命令会将参数的显示位置设置在常规文本基线之上，并使用较小的字体。
/*!
The series
1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
is called the \i {geometric series}.
*/如果参数中包含空格或其他标点符号，请将参数用大括号括起来。
\uicontrol
\uicontrol 命令用于标记用于UI控件的内容。在使用HTML时，该内容将以粗体形式显示。
另请参阅 \b。
\underline
\underline 命令会将其参数显示为带下划线的样式。
/*!
The \underline {F}ile menu gives the users the possibility
to edit an existing file, or save a new or modified
file, and exit the application.
*/如果参数中包含空格或其他标点符号，请将参数用大括号括起来。
\\（双反斜杠）
字符序列 \\ 将展开为一个反斜杠。
QDoc 命令总是以单个反斜杠开头。若要在文本中显示单个反斜杠，必须输入两个反斜杠。若要显示两个反斜杠，则必须输入四个。
/*!
The \\\\ command is useful if you want a
backslash to appear verbatim, for example,
writing C:\\windows\\home\\.
*/不过，如果您希望文本同时以等宽字体显示，可以使用 \c 命令，该命令会将反斜杠视为普通字符并进行渲染。例如：
/*!
The \\c command is useful if you want a
backslash to appear verbatim, and the word
that contains it written in a monospace font,
like this: \c {C:\windows\home\}.
*/--（半角连字符）
QDoc 将双连字符渲染为短破折号。那些旨在让输入内容原样显示的 QDoc 标记命令——例如\c 命令——不会将双连字符替换为短破折号字符。例如：
/*!
The \\c command -- useful if you want text in a monospace font --
is well documented.
*/然而，其他命令可能需要对连字符进行转义，以确保 QDoc 能按预期呈现输出。例如：
/*!
This \l {endash-sequence}{link to the -- (endash) sequence}
isn't escaped and QDoc therefore renders an endash in the link
text. However, the escaped
\l {endash-sequence}{link to the \-- (endash) sequence}
renders both hyphens as intended.
*/警告：请避免 在章节和页面标题中使用半破折号。如果标题中包含半破折号等特殊字符，则链接到该标题可能会失败。
另请参阅---（长破折号）。
---（长破折号）
QDoc 将三个连字符渲染为长破折号。旨在使输入内容原样显示的 QDoc 标记命令（例如\c 命令）不会将三个连字符替换为长破折号字符。例如：
/*!
The \\c command---useful when you want text to be rendered
verbatim---is well documented.
*/然而，其他命令可能需要对连字符进行转义，以确保 QDoc 能按预期渲染输出。例如：
/*!
This \l {emdash-sequence}{link to the --- (emdash) sequence}
isn't escaped and QDoc therefore renders an emdash in the link
text. However, the escaped
\l {emdash-sequence}{link to the -\-- (emdash) sequence}
renders both hyphens as intended.
*/注意： 此示例中的转义控制序列 是针对半角连字的。这样可以避免输出中出现连字后紧跟半角连字的情况。
警告：请避免 在章节和页面标题中使用“em”破折号。如果标题中包含“em”破折号等特殊字符，链接到该标题可能会失败。
另请参阅--（短破折号）。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
