C++ Documentation Style

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This page is part of the Qt Writing Guidelines.

Qt uses QDoc to generate the documentation for Qt C++ documentation.

To get started, familiarize yourself with how QDoc works and the basics of setting up a QDoc project.

• QDoc Manual
  • The QDoc Configuration File
  • Topic Commands
  • Context Commands
  • Markup Commands
  • Macros

The general guideline is: Make your documentation set consistent with the rest of Qt.

Follow existing C++ or QML documentation and make sure the documentation fits into the current structure.

Class Documentation

Class documentation is generated using the \class command and the name of the class as the first argument. For Qt, we document the C++ classes in the implementation file, .cpp.

/*!
 QCache
 A template class that provides a cache.
 QtCore
 tools
 shared



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:

code/doc_src_qcache.cpp 0

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

code/doc_src_qcache.cpp 1

… detailed description omitted

QPixmapCache, QHash, QMap
*/

Context commands add information about the class, such as its module or which version the class was added.

Some mandatory context commands are:

• \brief - the class' brief description. See section below on the Brief
• \since - the version to which the class was added.
• \inmodule - associates a class to a Qt module.

Other important context commands:

• \internal - marks the class as internal. Internal classes including their member functions do not appear in the public API documentation.

Note: It was decided that we will not backdate APIs, so only add the with the version number of an upcoming release. See https://codereview.qt.io/#change,43797

The Brief and Detailed Description

The brief description is marked with the \brief command and it is for summarizing the purpose or functionality of the class. QDoc adds the brief descriptions to the annotated lists and tables listing the C++ classes.

It is a good practice to begin a brief description with a verb, but a noun is appropriate in some areas. Ensure that the brief fits into a QDoc generated table such as as the Qt Network C++ Classes page.

Some common initial words for the brief:

• Provides...
• Contains...
• Generates...
• Convenience wrapper...
• A storage class...

The Detailed Description section starts after the brief description. It provides more information about the class. The detailed description may contain images, snippet code, or links to other relevant documents. There must be an empty line which separates the brief and detailed description.

Member Functions

Typically, function documentation is above its implementation in a .cpp file. For function documentation that is not immediately above the implementation, the \fn command is needed.

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

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

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

qstring/main.cpp 37

insert(), replace()
*/

The function documentation starts with a verb, indicating the operation the function performs. This also applies to constructors and destructors.

Some common verbs for function documentation:

• Constructs…- for constructors

• Destroys… - for destructors
• Returns… - for accessor functions

For memberfunctions, mandatory documentation are:

• \a - the parameters and parameter types

• \c - the return type in marked up text
• What the function does

For example, the code below generates the QBasicTimer::isActive() documentation.

/*!
    \fn bool QBasicTimer::isActive() const

    Returns \c true if the timer is running and has not been stopped; otherwise
    returns \c false.

    \sa start(), stop()
*/

Properties

The property documentation resides immediately above the read function's implementation. The topic-commands for properties is [1].

/*!
 QVariantAnimation::duration
 the duration of the animation

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

QAbstractAnimation::duration()
*/

Property documentation usually starts with "This property…", but these are alternate expressions: "This property holds…"

• "This property describes…"
• "This property represents…"
• "Returns true when… and also when…" - for properties that are read.
• "Sets the…" - for properties that configure a type.

Property documentation must include:

• description and behavior of the property
• accepted values for the property
• the default value of the property

Similar to functions, the default type may be linked or marked with the ' command.

An example of a value range style is:

The values range from .0 (no blur) to maximumRadius (maximum blur). By default, the property is set to .0 (no blur).

Signals, Notifiers, and Slots

The topic command for signals, notifiers, and slots is [2]. Signal documentation state when they are triggered or emitted.

/*!
 QAbstractTransition::triggered()

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

Signal documentation typically begin with "This signal is triggered when…". Here are alternate styles: "This signal is triggered when…"

• "Triggered when…"
• "Emitted when…"

For slots or notifiers, the condition when they are executed or triggered by a signal should be documented.

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

For properties that have overloaded signals, QDoc groups the overloaded notifiers together. To refer to a specifc version of a notifier or signal, simply refer to the property and mention that there are different versions of the notifier.

/*!
 QSpinBox::value
 the value of the spin box

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

Enums, Namespaces, and other Types

Enums, namespaces, and macros have a topic-command for their documentation: [3]

• [4]
• [5]

The language style for these types mention that they are an enum or a macro and continues with the type description.

For enumerations, the [6] command is used to list the values. QDoc creates a table containing the enum values.

/*!
 QSql::TableType

This enum type describes types of SQL tables.

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