文本标记
文本格式化命令指示如何呈现文本。
\参数标记
\a 命令告诉 QDoc 下一个单词是一个正式的参数名称。
当一个形参未被记录或拼写错误时，QDoc 会发出警告，因此当你记录一个函数时，应在函数描述中提及每个形参的名称，并在前面加上 \a 命令。参数名随后将以斜体显示。
形参名称可以用大括号括起来，但不是必须的。
\c （代码字体）
\c 命令用于在代码字体中显示变量名、用户定义的类名和 C++ 关键字（例如int 和for ）。
该命令使用空格字体渲染参数。如果要在代码字体中渲染的文本包含空格，请用大括号将整个文本括起来：
\c 命令在其参数中接受特殊字符\ ，并将其渲染为普通字符。因此，如果要使用嵌套命令，必须使用teletype (\tt)命令。
\详情（可折叠）
details和enddetails命令会生成一个可折叠的<details>元素，并带有一个<summary>来控制隐藏/可见状态。
生成 HTML 输出时，使用 \details 和 \enddetails 命令生成可折叠的<details> HTML 元素。该命令接收一个用大括号括起来的可选摘要字符串。这个可选参数指定了详细信息的可见标题。
例如，输入如下内容
/*!
\details {QDoc details}
\note You're looking at detailed information.
\enddetails
*/
如果 QDoc 正在生成 HTML，它将把这些命令翻译成
<summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div>
QDoc 将其渲染为
QDoc 详情
注意： 您正在查看详细信息。
对于任何其他输出格式，QDoc 会将内容作为普通段落生成，而忽略摘要字符串。此命令在 Qt6.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
当所有的类属性值都定义为用于渲染 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
*/
类变量名指的是 style.css 中的一个子句。
.variableName { font-family: courier; color: blue }
使用上面显示的variableName子句，示例将呈现为
具有复杂类型的全局变量：
- 第 14 行 globals.cpp 中的mutableComplex1
- globals.cpp 中的mutableComplex2，第 15 行
- globals.cpp 第 16 行的constComplex1
- 第 17 行 globals.cpp 中的constComplex2
注意： span命令不会导致新段落的开始。
另请参见\div.
\tm（商标）
\tm 命令表示其参数是一个商标。在生成页面时，QDoc 会将商标符号 `™` 添加到参数的第一次出现处。
在项目配置中，navigation.trademarkspage 变量用于定义包含商标相关文档的页面标题。
navigation.trademarkspage = Trademarks
如果设置了该变量，则商标符号的每次出现都会链接到商标页面。
注意： 在章节标题中，\tm 命令将被忽略，其参数将按原样呈现。
另请参阅\section1和 navigation.
\tt（电传字体）
\tt 命令将其参数渲染为单倍行距字体。除了 \tt 允许在参数中嵌套 QDoc 命令（如 \e、\b和\underline）外，该命令的行为与\c命令一样。
/*!
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 命令用于标记用于用户界面控制元素的内容。使用 HTML 时，输出将以粗体显示。
另请参见 \b。
\下划线
下划线命令会在参数上加下划线。
/*!
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\}.
*/
--（en 破折号）
QDoc 将双连字符渲染为 en 破折号。QDoc 标记命令（如 \c 命令）旨在使其输入内容逐字显示，因此不会将双连字符替换为 "en "破折号字符。例如
/*!
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.
*/
另请参阅--- （EM 破折号）。
----（英文破折号）
QDoc 将三连字符渲染为 en 破折号。QDoc 标记命令（如 \c 命令）旨在使其输入内容逐字显示，因此不会将三连字符替换为 en 破折号字符。例如
/*!
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.
*/
注意： 本例中的转义控制序列针对的是后破折号。这样可以避免输出中出现连字符后接中间破折号的情况。
另请参阅-- (en dash)。
© 2025 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.
