编写文档

QDoc 注释

文档包含在 QDoc 注释 中，以 /*! 和 */ 为界。请注意，这是在 C++、QML 和 JavaScript 中都有效的注释。

在 QDoc 注释中，//! 用作单行文档注释，它后面的任何内容（直到换行符），都会在生成的输出中省略。

QDoc 将解析 C++ 和 QML 文件来查找 QDoc 注释。要显式省略某种文件类型，请在 配置 文件中省略它。

QDoc 命令

QDoc 使用 命令 来检索关于文档的信息。主题 命令决定文档元素的类型，Context 命令提供关于主题的提示和信息，标记 命令提供 QDoc 如何格式化文档的信息。

QDoc 主题

每个 QDoc 注释必须有一个 主题 类型。一个主题将它与其他主题区分开来。要指定主题类型，可以使用 主题命令。

QDoc 会收集类似的主题，并为每个主题创建一个页面。例如，某个 C++ 类的所有枚举、属性、函数和类描述都将在同一页中。使用 \page 命令指定通用页面，参数是文件名。

主题命令示例：

• \enum —— 用于枚举文档
• \class —— 用于 C++ 类文档
• \qmltype —— 用于 QML 类型文档
• \page —— 用于创建一个页面。

QDoc 注释可以包含同一类别的多个主题命令，虽然有一些限制。这样，可以一次性编写一个注释来记录函数的所有重载（使用多个 \fn 命令）或 QML 属性组的所有属性（使用 \qmlproperty 命令）。

如果 QDoc 注释包含多个主题命令，有可能在后续注释中为单个主题提供额外的 Context 命令：

 /*!
     \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 命令用于创建不属于 source 的文档。该命令可以接受两个参数：文章的文件名和文档类型。文档类型有：

• howto
• overview
• tutorial
• faq
• attribution —— 用于记录许可证的属性
• article —— default 当没有类型时

 /*!
     \page altruism-faq.html faq
     \title Altruism Frequently Asked Questions

     \brief All the questions about altruism, answered.

     ...
 */

主题命令 页面有所有的主题命令。

主题 Context

Context 命令给 QDoc 一个关于主题 Context 的提示。例如，如果一个 C++ 函数被废弃了，则应使用 \deprecated 命令将其标记为废弃。同样，页面导航 和 页面标题 也给 QDoc 提供了额外的页面信息。

QDoc 将为这些 Context 创建额外的链接或页面。例如，使用 \group 命令创建一个组，成员的话用 \ingroup 命令。参数是组名。

Context 命令 页面有所有的 Context 命令。

文档标记

QDoc 可以对文本进行 标记，与其他标记或文档工具类似。当使用 \b 命令标记文本时，QDoc 可以将一段文本标记为 粗体。

 \b{This} text will be in \b{bold}.

标记命令 页面有所有的标记命令。

文档剖析

本质上，QDoc 要创建一个页面，必须有一些基本要素。

• 给 QDoc 的注释分配主题 —— 注释可以是页面、属性文档、类文档或任何可用的 主题命令。
• 给主题一个 Context —— 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 会根据它们的主题和 Context 收集它们。从这些片段中产生的文档将被生成到 QVector3D 类的文档中。

注意，如果文档在源代码中紧接在函数或类之前，那么它就不需要有主题。QDoc 会认为代码上方的文档就是该代码的文档。

使用 \page 命令可以创建一篇文章。第一个参数是 QDoc 将创建的 HTML 文件。该主题用 Context 命令，即 \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
 */

The section on 主题命令 部分概述了其他几种主题类型。