C++ Documentation Style: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 11: Line 11:
== Class Documentation ==
== Class Documentation ==


Class documentation is generated using the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#class-command command and the name of the class as the first argument.
Class documentation is generated using the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#class-command command and the name of the class as the first argument.


<code><br />/*!<br /> QCache<br /> A template class that provides a cache.<br /> QtCore<br /> tools<br /> shared
<code>
/*!
QCache
A template class that provides a cache.
QtCore
tools
shared






QCachelt;Key, Tgt; defines a cache that stores objects of type T<br /> associated with keys of type Key. For example, here's the<br /> definition of a cache that stores objects of type Employee<br /> associated with an integer key:
QCachelt;Key, Tgt; 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
code/doc_src_qcache.cpp 0
Line 27: Line 36:
… detailed description omitted
… detailed description omitted


QPixmapCache, QHash, QMap<br />'''/<br /></code>
QPixmapCache, QHash, QMap
<br />&quot;Context commands&amp;quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/14-qdoc-commands-contextcommands.html add information about the class, such as its module or<br />which version the class was added.
*/
<br />Some required context commands are:
</code>
<br />''' &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command - the class' brief description. '''mandatory'''<br />* &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/16-qdoc-commands-status.html#since-command - the version to which the class was added . '''mandatory''' (see '''Note''' section about backdating APIs)<br />* &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/19-qdoc-commands-grouping.html#inmodule-command - associates a class to a Qt module. '''mandatory'''<br />* &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/16-qdoc-commands-status.html#internal-command - marks the class as internal. Internal classes do not appear in the public API documentation.
 
"Context commands":http://doc-snapshot.qt.io/qt5-stable/qdoc/14-qdoc-commands-contextcommands.html add information about the class, such as its module or
which version the class was added.
 
Some required context commands are:
 
''' "":http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command - the class' brief description. '''mandatory'''
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/16-qdoc-commands-status.html#since-command - the version to which the class was added . '''mandatory''' (see '''Note''' section about backdating APIs)
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/19-qdoc-commands-grouping.html#inmodule-command - associates a class to a Qt module. '''mandatory'''
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/16-qdoc-commands-status.html#internal-command - 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 with the version number of an upcoming release. See https://codereview.qt.io/#change,43797
'''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
Line 36: Line 54:
=== The Brief and Detailed Description ===
=== The Brief and Detailed Description ===


The '''brief description''' is marked with the &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command 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 '''brief description''' is marked with the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command 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.
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.
Line 42: Line 60:
== Member Functions ==
== 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 &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command is needed.
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 "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command is needed.


<code><br />/*!<br /> QString &amp;QString::remove(int position, int n)
<code>
/*!
QString &amp;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.
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<br /> truncated at the specified position.
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
qstring/main.cpp 37


insert(), replace()<br />'''/<br /></code>
insert(), replace()
<br />The function documentation starts with a verb, indicating the operation the function performs. This also applies to constructors and destructors.
*/
<br />Some common verbs for function documentation:<br />''' &quot;Constructs…&quot; - for constructors<br />* &quot;Destroys…&quot; - for destructors<br />* &quot;Returns…&quot; - for accessor functions
</code>
 
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 "":http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#a-command command marks the parameter in the documentation.
The return type documentation should link to the type documentation or be marked with the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#c-command command in the case of boolean values.
 
<code>
/*!
Returns rue if a QScroller object was already created for target; alse otherwise.
 
scroller()
*/
</code>


The function documentation must document:<br />* the return type<br />* the parameters<br />* the actions of the functions
h2. Properties


The &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#a-command command marks the parameter in the documentation.<br />The return type documentation should link to the type documentation or be marked with the &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#c-command command in the case of boolean values.
The property documentation resides immediately above the read function's implementation. The "topic-commands":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for properties is "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#property-command.


<code><br />/*!<br /> Returns rue if a QScroller object was already created for target; alse otherwise.
<code>
/*!
QVariantAnimation::duration
the duration of the animation


scroller()<br />'''/<br /></code>
This property describes the duration in milliseconds of the
<br />h2. Properties
animation. The default duration is 250 milliseconds.
<br />The property documentation resides immediately above the read function's implementation. The &quot;topic-commands&amp;quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for properties is &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#property-command.
<br /><code><br />/'''!<br /> QVariantAnimation::duration<br /> the duration of the animation


This property describes the duration in milliseconds of the<br /> animation. The default duration is 250 milliseconds.
QAbstractAnimation::duration()
*/
</code>


QAbstractAnimation::duration()<br />'''/<br /></code>
Property documentation usually starts with "This property…", but these are alternate expressions:
<br />Property documentation usually starts with &quot;This property…&quot;, but these are alternate expressions:<br />''' &quot;This property holds…&quot;<br />* &quot;This property describes…&quot;<br />* &quot;This property represents…&quot;<br />* &quot;Returns rue when… and alse when…&quot; - for properties that are read.<br />* &quot;Sets the…&quot; - for properties that configure a type.
''' "This property holds…"
* "This property describes…"
* "This property represents…"
* "Returns rue when… and alse when…" - for properties that are read.
* "Sets the…" - for properties that configure a type.


Property documentation must include:<br />* description and behavior of the property<br />* accepted values for the property<br />* the default value of the property<br />Similar to functions, the default type may be linked or marked with the '''' command.
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:<br /><code>The values range from .0 (no blur) to maximumRadius (maximum blur). By default, the property is set to .0 (no blur).<code>
An example of a value range style is:
<code>The values range from .0 (no blur) to maximumRadius (maximum blur). By default, the property is set to .0 (no blur).<code>


== Signals, Notifiers, and Slots ==
== Signals, Notifiers, and Slots ==


The &quot;topic command&amp;quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for signals, notifiers, and slots<br />is &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command. Signal documentation state when they are triggered or emitted.
The "topic command":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for signals, notifiers, and slots
is "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command. Signal documentation state when they are triggered or emitted.
 
</code>
/*!
QAbstractTransition::triggered()


</code><br />/*!<br /> QAbstractTransition::triggered()
This signal is emitted when the transition has been triggered (after
onTransition() has been called).
*/
<code>


This signal is emitted when the transition has been triggered (after<br /> onTransition() has been called).<br />'''/<br /><code>
Signal documentation typically begin with "This signal is triggered when…". Here are alternate styles:
<br />Signal documentation typically begin with &quot;This signal is triggered when…&quot;. Here are alternate styles:<br />''' &quot;This signal is triggered when…&quot;<br />* &quot;Triggered when…&quot;<br />* &quot;Emitted when…&quot;
''' "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.<br />* &quot;Executed when…&quot;<br />* &quot;This slot is executed when…&quot;
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.
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.


</code><br />/*!<br /> QSpinBox::value<br /> the value of the spin box
</code>
/*!
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.
*/
<code>
 
h2. Enums, Namespaces, and other Types


setValue() will emit valueChanged() if the new value is different<br /> from the old one. The {QSpinBox::}{value} property has a second notifier<br /> signal which includes the spin box's prefix and suffix.<br />'''/<br /><code>
Enums, namespaces, and macros have a "topic-command":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for their documentation:
<br />h2. Enums, Namespaces, and other Types
''' "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#enum-command
<br />Enums, namespaces, and macros have a &quot;topic-command&amp;quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for their documentation:<br />''' &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#enum-command<br />* &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#typedef-command<br />* &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#macro-command
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#typedef-command
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#macro-command


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


For enumerations, the &quot;&quot;:http://doc-snapshot.qt.io/qt5-stable/qdoc/10-qdoc-commands-tablesandlists.html#value-command command is used to list the values. QDoc creates a table containing the enum values.
For enumerations, the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/10-qdoc-commands-tablesandlists.html#value-command command is used to list the values. QDoc creates a table containing the enum values.


</code><br />/*!<br /> QSql::TableType
</code>
/*!
QSql::TableType


This enum type describes types of SQL tables.
This enum type describes types of SQL tables.


Tables All the tables visible to the user.<br /> SystemTables Internal tables used by the database.<br /> Views All the views visible to the user.<br /> AllTables All of the above.<br />*/
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.
*/

Revision as of 10:57, 25 February 2015

h1. 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 "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#class-command command and the name of the class as the first argument.

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



QCachelt;Key, Tgt; 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":http://doc-snapshot.qt.io/qt5-stable/qdoc/14-qdoc-commands-contextcommands.html add information about the class, such as its module or which version the class was added.

Some required context commands are:

"":http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command - the class' brief description. mandatory

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 "":http://doc-snapshot.qt.io/qt5-stable/qdoc/11-qdoc-commands-specialcontent.html#brief-command 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 "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command is needed.

/*!
 QString &amp;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

The function documentation must document:

  • the return type
  • the parameters
  • the actions of the functions

The "":http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#a-command command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/04-qdoc-commands-textmarkup.html#c-command command in the case of boolean values.

/*!
 Returns rue if a QScroller object was already created for target; alse otherwise.

scroller()
*/

h2. Properties

The property documentation resides immediately above the read function's implementation. The "topic-commands":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for properties is "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#property-command.

/*!
 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 rue when… and alse 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).<code>

== Signals, Notifiers, and Slots ==

The "topic command":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for signals, notifiers, and slots
is "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#fn-command. 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.
  • /
h2. Enums, Namespaces, and other Types

Enums, namespaces, and macros have a "topic-command":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html for their documentation:
''' "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#enum-command
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#typedef-command
* "":http://doc-snapshot.qt.io/qt5-stable/qdoc/13-qdoc-commands-topics.html#macro-command

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

For enumerations, the "":http://doc-snapshot.qt.io/qt5-stable/qdoc/10-qdoc-commands-tablesandlists.html#value-command 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.
  • /