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.
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:
Read the QDoc Manual's Relating Things page for command usage.