编写文档
QDoc 注释
文档内容包含在QDoc注释中，由 /*! 和 */ 注释符号分隔。请注意，这些在C++和QML中都是有效的注释。
在 QDoc 注释中，//! 用于表示单行文档注释；该注释本身及其后直至换行符的所有内容，在生成的输出中均会被省略。
QDoc 会解析 C++ 和 QML 文件以查找 QDoc 注释。若要明确排除某种文件类型，请在配置文件中将其排除在外。
QDoc 命令
QDoc通过命令来获取文档信息。Topic 命令用于确定文档元素的类型，context 命令提供有关某个主题的提示和信息，而markup 命令则指定 QDoc 应如何对某段文档进行格式化。
QDoc 主题
每个 QDoc 注释都必须具有一个主题类型。主题用于将其与其他主题区分开来。要指定主题类型，请使用多种主题命令中的一种。
QDoc 会收集相似的主题，并为每个主题创建一个页面。例如，某个特定 C++ 类的所有枚举、属性、函数和类描述都会集中在一个页面中。通用页面通过 \page 命令指定，其参数即为文件名。
主题命令示例：
多个主题
一条 QDoc 注释可以在同一类别中包含多个主题命令，但存在某些限制。这样，就可以通过一条注释来记录一个函数的所有重载（使用多个 \fn 命令），或一次性记录 QML 属性组中的所有属性（使用 \qmlproperty 命令）一次性完成。
如果一个 QDoc 注释包含多个主题命令，则可以在后续注释中为各个主题提供额外的上下文命令：
/*!
\qmlproperty string Type::element.name
\qmlproperty int Type::element.id
\brief Holds the element name and id.
*/
/*!
\qmlproperty int Type::element.id
\readonly
*/在此，后续注释将element.id属性标记为只读，而element.name仍可写入。
注意： 后续注释 不能包含任何额外文本，只能包含用于记录该项目上下文的上下文命令。
“主题命令”页面提供了所有可用主题命令的相关信息。
主题上下文
上下文命令可向 QDoc 提供有关该主题上下文的提示。例如，如果某个 C++ 函数已被弃用，则应使用 \deprecated 命令将其标记为已弃用。同样，页面导航和页面标题也会向 QDoc 提供额外的页面信息。
QDoc 会针对这些上下文创建额外的链接或页面。例如，使用 \group 命令创建，其成员则使用 \ingroup 命令。组名作为参数提供。
“上下文命令”页面列出了所有可用的上下文命令。
文档标记
QDoc 可以像其他标记或文档工具一样对文本进行标记。当文本使用 \b 命令进行标记时，会将该文本段落标记为粗体。
\b{This} text will be in \b{bold}.“标记命令”页面列出了所有可用的标记命令。
文档结构解析
基本上，QDoc 要生成一个页面，必须具备一些基本要素。
- 为 QDoc 注释分配主题——注释可以是页面、属性文档、类文档，或是任何可用的主题命令。
- 为主题指定上下文——QDoc 可以将某些主题与其他页面关联，例如当文档被标记为 \deprecated标记文档时关联弃用元素。
- 使用标记命令标记文档的各个部分——QDoc 可以创建布局并为文档设置格式。
在 Qt 中，QVector3D 类的文档通过以下 QDoc 注释进行说明：
/*!
\class QVector3D
\brief The QVector3D class represents a vector or vertex in 3D space.
\since 4.6
\ingroup painting-3D
Vectors are one of the main building blocks of 3D representation and
drawing. They consist of three coordinates, traditionally called
x, y, and z.
The QVector3D class can also be used to represent vertices in 3D space.
We therefore do not need to provide a separate vertex class.
\note By design values in the QVector3D instance are stored as \c float.
This means that on platforms where the \c qreal arguments to QVector3D
functions are represented by \c double values, it is possible to
lose precision.
\sa QVector2D, QVector4D, QQuaternion
*/它有一个构造函数QVector3D::QVector3D()，该构造函数的文档说明如下所示：
/*!
\fn QVector3D::QVector3D(const QPoint& point)
Constructs a vector with x and y coordinates from a 2D \a point, and a
z coordinate of 0.
*/不同的注释可能位于不同的文件中，QDoc 会根据其主题和上下文将它们汇总起来。这些片段生成的文档最终会被整合到QVector3D 类的文档中。
请注意，如果文档紧接在源代码中的函数或类之前，则无需指定主题。QDoc 会默认将代码上方的文档视为该代码的文档。
文章可通过 \page 命令创建。其第一个参数是 QDoc 将生成的 HTML 文件。主题会通过上下文命令（如 \title 和 \nextpage 命令来补充主题内容。QDoc 还有其他一些命令，例如 \list 命令等。
/*!
\page generic-guide.html
\title Generic QDoc Guide
\nextpage Creating QDoc Configuration Files
There are three essential materials for generating documentation with QDoc:
\list
\li \c QDoc binary (\c {qdoc})
\li \c qdocconf configuration files
\li \c Documentation in \c C++, \c QML, and \c .qdoc files
\endlist
*/“主题命令”一节概述了其他几种主题类型。
© 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.
