编写文档
QDoc 注释
文档包含在 QDoc注释中，以 /*! 和 */ 注释分隔。请注意，这些注释在 C++ 和 QML 中都是有效的。
在 QDoc 注释中，//! 用作单行文档注释；在生成的输出中，注释本身和注释后的任何内容（直到换行符为止）都将被省略。
QDoc 将解析 C++ 和 QML 文件以查找 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仍为可写。
注意： 后续注释 不能包含任何附加文本，只能包含记录项目上下文的上下文命令。
\page命令用于创建不属于源文档的文章。该命令还可以接受两个参数：文章的文件名和文档类型。可能的类型有
howtooverviewtutorialfaqattribution- 用于记录许可证属性article- 无类型时默认
/*!
\page altruism-faq.html
\title Altruism Frequently Asked Questions
\brief All the questions about altruism, answered.
...
*/主题命令页面包含所有可用主题命令的信息。
主题上下文
上下文命令可为 QDoc 提供有关主题上下文的提示。例如，如果一个 C++ 函数已被弃用，则应使用\deprecated命令将其标记为已被弃用。同样，页面导航和页面标题也为 QDoc 提供了额外的页面信息。
QDoc 将为这些上下文创建额外的链接或页面。例如，使用\group命令创建一个组，使用\ingroup命令创建成员。组名作为参数提供。
上下文命令页面列出了所有可用的上下文命令。
文档标记
QDoc 可以对文本进行标记，这与其他标记或文档工具类似。当使用\b命令标记文本时，QDoc 可以用粗体标记文本的某一部分。
\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() ，该构造函数的 QDoc 注释如下：
/*!
\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
*/主题命令部分概述了其他几种主题类型。
© 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.
