C++ Documentation Style
C++ Documentation Style
This page is part of the Qt Writing Guidelines.
Though there are exceptions, these guidelines should be followed. Keeping that in mind, at least be consistent within the page. Meaning, the class member documentation should have the same style.
To generate the documentation, QDoc goes through the source code and generates documentation for C++ types such as classes. QDoc then associates member functions, properties, and other types to the appropriate class.
Note that the documentation must be in the implementation files such as .cpp files.
Class Documentation
Class documentation is generated using the \class [doc-snapshot.qt.io] command and the name of the class as the first argument.
Context commands [doc-snapshot.qt.io] add information about the class, such as its module or
which version the class was added.
Some required context commands are:
- \brief [doc-snapshot.qt.io] – the class’ brief description. mandatory
- \since [doc-snapshot.qt.io] – the version to which the class was added . mandatory (see Note section about backdating APIs)
- \inmodule [doc-snapshot.qt.io] – associates a class to a Qt module. mandatory
- \internal [doc-snapshot.qt.io] – marks the class as internal. Internal classes do not appear in the public API documentation.
Note: It was decided that we will not backdate APIs, so only add the \since 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 [doc-snapshot.qt.io] 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.
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 immediately precedes the implementation of the function in the .cpp file. For function documentation that is not immediately above the implementation, the \fn [doc-snapshot.qt.io] is needed.
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
The function documentation must document:
- the return type
- the parameters
- the actions of the functions
The \a [doc-snapshot.qt.io] command marks the parameter in the documentation.
The return type documentation should link to the type documentation or be marked with the \c [doc-snapshot.qt.io] command in the case of boolean values.
Properties
The property documentation resides immediately above the read function’s implementation. The topic-commands [doc-snapshot.qt.io] for properties is \property [doc-snapshot.qt.io].
Property documentation usually starts with “This property…”, but these are alternate expressions:
- “This property holds…”
- “This property describes…”
- “This property represents…”
- “Returns \c true when… and \c false 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 \c command.
An example of a value range style is:
Signals, Notifiers, and Slots
The topic command [doc-snapshot.qt.io] for signals, notifiers, and slots
is \fn [doc-snapshot.qt.io]. Signal documentation state when they are triggered or emitted.
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.
Enums, Namespaces, and other Types
Enums, namespaces, and macros have a topic-command [doc-snapshot.qt.io] for their documentation:
The language style for these types mention that they are an enum or a macro and
continues with the type description.
For enumerations, the \value [doc-snapshot.qt.io] command is used to list the values. QDoc creates a table containing the enum values.