编写文档

QDoc注释

文档包含在QDoc 注释中，由 /*! 和 */ 注释分隔。请注意，这些是C++和QML中的有效注释。

在QDoc注释中，//! 用于单行文档注释；注释本身以及其后的任何内容（直到换行符）都会从生成的输出中省略。

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

QDoc命令

QDoc使用命令来检索有关文档的信息。 Topic 命令确定文档元素的类型，context 命令提供有关主题的提示和信息，而 markup 命令提供有关QDoc如何格式化文档片段的信息。

QDoc主题

每个QDoc注释都必须有一个主题类型。主题将区分其他主题。要指定主题类型，请使用多个主题命令之一。

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

主题命令示例

\enum - 用于枚举文档
\class - 用于C++类文档
\qmltype - 用于QML类型文档
\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 命令用于创建不属于源文档的文章。该命令还可以接受两个参数：文章的文件名和文档类型。可能的类型有

howto
概述
教程
faq
attribution - 用于记录许可归属
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 中，使用以下 QDoc 注释对 QVector3D 类进行了文档化

/*!
    \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
*/

关于主题命令的章节概述了其他几个主题类型。

创建 QDoc 配置文件文档类别