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++ 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.

The example below generates the QCache class documentation:

/*!
 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 when 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-project.org/c/qt/qtbase/+/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. Ensure that the brief fits into a QDoc generated table such as as the Qt Network C++ Classes page.

Note: QDoc requires a brief description and generates a warning if the brief is empty.

In general, the brief statements

• The <C++ class> class provides...
• The <C++ class> class is the base class of...
• The <C++ class> class manipulates...

...or use other verbs that describe the class in general.

Things to note:

• QDoc requires a brief description and generates a warning if the brief is empty.
• Terminate the brief description with a period and complete the sentence.
• The brief statement structure differs for C++ APIs, QML APIs, overviews, and examples.

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, member function documentation is above its implementation in a .cpp file and QDoc can associate the function with the documentation. If the function documentation is elsewhere, the \fn command is needed. QDoc then generates a list of member functions in the class documentation.

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

Member function documentation must include:

• \a - the parameters and parameter types

• \c - the return type in marked up text
• \since - the version when the function added
• Preconditions, behaviors, and consequences from using the member function

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 command is for documenting properties. If the documentation is above the implementation, then QDoc can connect the documentation with the property. QDoc then generates a listing of properties in the class documentation.

Property documentation usually start with these expressions:

• This property holds…

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

Property documentation must include:

• \c command to mark property values such as accepted, minimum or maximum ranges, and default values
• \brief command which QDoc uses as the brief description
• \since - the version when the property was added.

The example below generates documentation for the QLabel::wordWrap property.

/*!
    \property QLabel::wordWrap
    \brief the label's word-wrapping policy

    If this property is \c true then label text is wrapped where
    necessary at word-breaks; otherwise it is not wrapped at all.

    By default, word wrap is disabled.

    \sa text
*/
void QLabel::setWordWrap(bool on)

QDoc generates sections and text based on the Q_PROPERTY() macro and the corresponding accessors and signals.

Signals, notifiers, and slots

Signal, slot, and notifier documentation is also documented with the \fn command. Therefore, the documentation for signals, slots, and notifiers is similar to member functions. QDoc then generates a listing of signals, slots, and notifiers in the class documentation.

The code below generates signal documentation for QWidget::windowTitleChanged().

/*!
    \fn void QWidget::windowTitleChanged(const QString &title)

    This signal is emitted when the window's title has changed, with the
    new \a title as an argument.

    \since 5.2
*/
void QWidget::setWindowTitle(const QString &title)

Documentation must include:

• \a - the parameters and parameter types

• \c - the return type in marked up text
• \since - the version when the function added
• Preconditions, behaviors, and consequences

Here are common sentence structures for signals:

• This signal is triggered when…

• Triggered when…
• Emitted when…

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

• Executed when…
• This slot is executed when…

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

For an example, see the generated documentation for QSpinBox::value property which has a notifier and a signal.

/*!
 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 and other Types

For other types such as enums, namespaces, and macros, QDoc has a topic command for each. Familiarize yourself with the topic commands page of the QDoc Manual.

For C++ enums, use the \enum command and:

• \value for each enum value
• \omitvalue values not intended to be visible. Otherwise, QDoc will emit a warning for undocumented values
• \since - the version when the enum was added.

QDoc will then generate a table with the values. The code below generates the documentation for QBoxLayout::Direction.

/*!
    \enum QBoxLayout::Direction

    This type is used to determine the direction of a box layout.

    \value LeftToRight  Horizontal from left to right.
    \value RightToLeft  Horizontal from right to left.
    \value TopToBottom  Vertical from top to bottom.
    \value BottomToTop  Vertical from bottom to top.

    \omitvalue Down
    \omitvalue Up
*/

Relating and giving context

QDoc creates an internal structure of the implementation and can generate documentation from this structure. API developers can fine tune QDoc's output by relating the implementations and by giving context to the APIs. For Qt documentation, there are certain things that Qt developers deem as internal or in order to present a cleaner API, abstract implementation details.

For C++ API, in many cases, QDoc can assume much of the API structure such as C++ inheritance, but it needs help to abstract and properly connect APIs.

To fine tune relationships and give context to QDoc, here are some common commands:

• \internal
• \overload
• \reimp
• \relates

Read the QDoc Manual's Relating Things page for command usage.