文档类别 ◦ QML 文档样式

目录

C++ 文档样式

为了生成文档，QDoc 会遍历源代码并为 C++ 类型（例如类）生成文档。然后 QDoc 将成员函数、属性和其他类型关联到相应的类。

请注意，文档必须在 .cpp 等实现文件中。

类文档

类文档是用 \class 命令和类名作为第一个参数生成的。

 /*!
     \class QCache
     \brief The QCache class is a template class that provides a cache.

     \ingroup tools
     \ingroup shared

     \reentrant

     QCache\<Key, T\> defines a cache that stores objects of type T
     associated with keys of type Key. For example, here's the
     definition of a cache that stores objects of type Employee
     associated with an integer key:

     \snippet code/doc_src_qcache.cpp 0

     Here's how to insert an object in the cache:

     \snippet code/doc_src_qcache.cpp 1

     ... detailed description omitted

     \sa QPixmapCache, QHash, QMap
 */

Context 命令添加了关于类的信息，例如它的模块或类被添加的版本。

一些常见的 Context 命令：

  • \brief —— 类的简要描述（强制）
  • \since —— 该类被添加到哪个版本（强制）
  • \internal —— 标记该类为内部类。内部类不会出现在公共 API 文档中。

简要描述和详细说明

简要描述 是用 \brief 命令标记的，用来总结类的目的或功能。对于 C++ 类，QDoc 将获取该类并为该类创建注释信息。这些注释信息会出现在显示该类的列表和表格中。

C++ 简介应该这样开始：

 "The <C++ class name> class"

详细描述 部分在简要描述之后。它提供了有关该类的更多信息。详细描述可能包含图片、代码片段或其他相关文档的链接。简要描述和详细描述之间必须有一行空行。

成员函数

通常，函数文档紧接在 .cpp 文件中函数的实现之前。对于不在实现之上的函数文档，需要 \fn。

 /*!
   \fn QString &QString::remove(int position, int n)

   Removes \a n characters from the string, starting at the given \a
   position index, and returns a reference to the string.

   If the specified \a position index is within the string, but \a
   position + \a n is beyond the end of the string, the string is
   truncated at the specified \a position.

   \snippet qstring/main.cpp 37

   \sa insert(), replace()
 */
 QString &QString::remove(int pos, int len)

函数文档以动词开头，表示函数执行的操作。这也适用于构造函数和析构函数。

一些函数文档的常用动词：

  • "Constructs..." —— 用于构造函数
  • "Destroys..." —— 用于析构函数
  • "Returns..." —— 用于 Accessor 函数（就是 getter 函数）

函数的文档必须记录：

  • 返回类型
  • 参数
  • 函数的作用

\a 命令标记文档中的参数。返回类型的文档应该链接到类型文档，或者在是布尔值的情况下用 \c 命令标记。

 /*!
     Returns \c true if a QScroller object was already created for \a target; \c false otherwise.

     \sa scroller()
 */
 bool QScroller::hasScroller(QObject *target)

属性

属性文档紧靠在读取函数的实现之上。属性的 主题命令 是 \property。

 /*!
     \property QVariantAnimation::duration
     \brief the duration of the animation

     This property describes the duration in milliseconds of the
     animation. The default duration is 250 milliseconds.

     \sa QAbstractAnimation::duration()
  */
 int QVariantAnimation::duration() const

属性文档通常以 “This property...” 开头，有一些可替代的表达：

  • "This property holds..."
  • "This property describes..."
  • "This property represents..."
  • "Returns true when... and false when..." —— 用于读取的属性。
  • "Sets the..." —— 用于写入的属性。

属性文档必须包括：

  • 属性的描述和行为
  • 该属性的可接受值
  • 该属性的默认值

与 函数 类似，默认类型可以用 \c 命令链接或标记。

值范围样式的例子：

值范围从 0.0（无模糊）到 maximumRadius（最大模糊）。默认情况下，该属性被设置为 0.0（无模糊）。

信号、通知和槽

信号、通知和槽的 主题命令 是 \fn。信号文档描述它们的触发或发送。

 /*!
   \fn QAbstractTransition::triggered()

   This signal is emitted when the transition has been triggered (after
   onTransition() has been called).
 */

信号文档通常以 “This signal is triggered when...” 开头。以下是可替代的表达：

  • "This signal is triggered when..."
  • "Triggered when..."
  • "Emitted when..."

应描述槽函数被执行或信号被触发的条件。

  • "Executed when..."
  • "This slot is executed when..."

对于具有重载信号的属性，QDoc 将重载的通知组合在一起。要引用特定版本的通知或信号，只需引用该属性并提及通知有不同版本。

 /*!
 \property QSpinBox::value
 \brief the value of the spin box

 setValue() will emit valueChanged() if the new value is different
 from the old one. The \l{QSpinBox::}{value} property has a second notifier
 signal which includes the spin box's prefix and suffix.
 */

枚举、命名空间和其他类型

枚举、命名空间和宏的文档都有一个 主题命令：

这些类型描述它们是枚举或宏，然后进行其他描述。

对于枚举，\value 命令用于列出值。 QDoc 为枚举创建一个值表。

 /*!
     \enum QSql::TableType

     This enum type describes types of SQL tables.

     \value Tables  All the tables visible to the user.
     \value SystemTables  Internal tables used by the database.
     \value Views  All the views visible to the user.
     \value AllTables  All of the above.
 */

文档类别 ◦ QML 文档样式