Writing Documentation

QDoc Comments

Documentation is contained within QDoc comments, delimited by /*! and */ comments. Note that these are valid comments in C++ and QML.

Within a QDoc comment, //! is used as a single-line documentation comment; the comment itself and anything after it, until a newline, is omitted from the generated output.

QDoc will parse C++ and QML files to look for QDoc comments. To explicitly omit a certain file type, omit it from the configuration file.

QDoc Commands

QDoc uses commands to retrieve information about the documentation. Topic commands determine the type of documentation element, the context commands provide hints and information about a topic, and markup commands provide information on how QDoc should format a piece of documentation.

QDoc Topics

Each QDoc comment must have a topic type. A topic distinguishes it from other topics. To specify a topic type, use one of the several topic commands.

QDoc will collect similar topics and create a page for each one. For example, all the enumerations, properties, functions, and class description of a particular C++ class will reside in one page. A generic page is specified using the \page command and the filename is the argument.

Example of topic commands:

• \enum - for enumeration documentation
• \class - for C++ class documentation
• \qmltype - for QML type documentation
• \page - for creating a page.

A QDoc comment can contain multiple topic commands in the same category, with some restrictions. This way, it's possible to write a single comment that documents all overloads of a function (using multiple \fn commands), or all properties in a QML property group (using \qmlproperty commands) in one go.

If a QDoc comment contains multiple topic commands, it's possible to provide additional context commands for individual topics in follow-up comments:

 /*!
     \qmlproperty string Type::element.name
     \qmlproperty int Type::element.id

     \brief Holds the element name and id.
 */

 /*!
     \qmlproperty int Type::element.id
     \readonly
 */

Here, the follow-up comment marks the element.id property as read-only, while element.name remains writable.

The \page command is for creating articles that are not part of source documentation. The command can also accept two arguments: the file name of the article and the documentation type. The possible types are:

• howto
• overview
• tutorial
• faq
• attribution - used for documenting license attributions
• article - default when there is no type

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

     \brief All the questions about altruism, answered.

     ...
 */

The Topic Commands page has information on all of the available topic commands.

Topic Contexts

Context commands give QDoc a hint about the context of the topic. For example, if a C++ function is deprecated, then it should be marked as such with the \deprecated command. Likewise, page navigation and page title give extra page information to QDoc.

QDoc will create additional links or pages for these contexts. For example, a group is created using the \group command and the members have the \ingroup command. The group name is supplied as an argument.

The Context Commands page has a listing of all the available context commands.

Documentation Markup

QDoc can do markup of text similar to other markup or documentation tools. QDoc can mark a section of text in bold, when the text is marked up with the \b command.

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

The Markup Commands page has a full listing of the available markup commands.

Anatomy of Documentation

Essentially, for QDoc to create a page, there must be some essential ingredients present.

• Assign a topic to a QDoc comment - A comment could be a page, a property documentation, a class documentation, or any of the available topic commands.
• Give the topic a context - QDoc can associate certain topics to other pages such as associating deprecated functions when the documentation is marked with \deprecated.
• Mark sections of the document with markup commands - QDoc can create layouts and format the documentation for the documentation.

In Qt, the QVector3D class was documented with the following QDoc comment:

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

It has a constructor, QVector3D::QVector3D(), which was documented with the following QDoc comment:

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

The different comments may reside in different files and QDoc will collect them depending on their topic and their context. The resulting documentation from the snippets are generated into the QVector3D class documentation.

Note that if the documentation immediately precedes the function or class in the source code, then it does not need to have a topic. QDoc will assume that the documentation above the code is the documentation for that code.

An article is created using \page command. The first argument is the HTML file that QDoc will create. The topic is supplemented with context commands, the \title and \nextpage commands. There are several other QDoc commands such as the \list command.

 /*!
     \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 topic commands gives an overview on several other topic types.