Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtwritingstyle-cpp.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page qtwritingstyle-cpp.html
6
\title C++ Documentation Style
7
\brief Style guidelines for C++ documentation
8
9
To generate the documentation, QDoc goes through the source code and generates
10
documentation for C++ types such as classes. QDoc then associates member
11
functions, properties, and other types to the appropriate class.
12
13
Note that the documentation must be in the implementation files such as \c .cpp.
14
15
\section1 Class Documentation
16
17
Class documentation is generated using the \l{class-command}{\\class} command and
18
the name of the class as the first argument.
19
20
\snippet examples/cpp.qdoc.sample class
21
22
\l{Context commands} add information about the class, such as its module or
23
which version the class was added.
24
25
Some common context commands are:
26
\list
27
\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory)
28
\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory)
29
\li \l{internal-command}{\\internal} - marks the class as internal. Internal
30
classes do not appear in the public API documentation.
31
\endlist
32
33
34
\section2 The Brief and Detailed Description
35
36
The \e{brief description} is marked with the \l{brief-command}{\\brief} command
37
and it is for summarizing the purpose or functionality of the class. For C++
38
classes, QDoc will take the class and create annotated information for the
39
class. The annotated information appears in lists and tables which display the
40
class.
41
42
The C++ brief should start with:
43
\code
44
"The <C++ class name> class"
45
\endcode
46
47
The \e{detailed description} section starts after the brief description. It
48
provides more information about the class. The detailed description may contain
49
images, snippet code, or links to other relevant documents. There
50
must be an empty line which separates the brief and detailed description.
51
52
\section1 Member Functions
53
54
Typically, function documentation immediately precedes the implementation of the
55
function in the \c .cpp file. For function documentation that is not immediately
56
above the implementation, the \l{fn-command}{\\fn} is needed.
57
58
\snippet examples/cpp.qdoc.sample function
59
60
The function documentation starts with a verb, indicating the operation the
61
function performs. This also applies to constructors and destructors.
62
63
Some common verbs for function documentation:
64
\list
65
\li "Constructs..." - for constructors
66
\li "Destroys..." - for destructors
67
\li "Returns..." - for accessor functions
68
\endlist
69
70
The function documentation must document:
71
\list
72
\li the return type
73
\li the parameters
74
\li the actions of the functions
75
\endlist
76
77
The \l{a-command}{\\a} command marks the parameter in the documentation.
78
The return type documentation should link to the type documentation or be
79
marked with the \l{c-command}{\\c} command in the case of boolean values.
80
81
\snippet examples/cpp.qdoc.sample return
82
83
\section1 Properties
84
85
The property documentation resides immediately above the read function's
86
implementation. The \l{writing-topic-commands}{topic command} for properties is
87
\l{property-command}{\\property}.
88
89
\snippet examples/cpp.qdoc.sample property
90
91
Property documentation usually starts with "This property...", but these are
92
alternate expressions:
93
\list
94
\li "This property holds..."
95
\li "This property describes..."
96
\li "This property represents..."
97
\li "Returns \c true when... and \c false when..." - for properties that
98
are read.
99
\li "Sets the..." - for properties that configure a type.
100
\endlist
101
102
Property documentation must include:
103
\list
104
\li description and behavior of the property
105
\li accepted values for the property
106
\li the default value of the property
107
\endlist
108
Similar to \l{Member Functions}{functions}, the default type may be linked
109
or marked with the \c{\c} command.
110
111
An example of a value range style is:
112
\quotation
113
The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur).
114
\endquotation
115
116
\section1 Signals, Notifiers, and Slots
117
The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots
118
is \l{fn-command}{\\fn}. Signal documentation state when they are triggered
119
or emitted.
120
121
\snippet examples/cpp.qdoc.sample signals
122
123
Signal documentation typically begin with "This signal is triggered when...".
124
Here are alternate styles:
125
\list
126
\li "This signal is triggered when..."
127
\li "Triggered when..."
128
\li "Emitted when..."
129
\endlist
130
131
For slots or notifiers, the condition when they are executed or triggered by
132
a signal should be documented.
133
\list
134
\li "Executed when..."
135
\li "This slot is executed when..."
136
\endlist
137
138
For properties that have overloaded signals, QDoc groups the overloaded
139
notifiers together. To refer to a specific version of a notifier or signal,
140
simply refer to the property and mention that there are different versions of
141
the notifier.
142
143
\snippet examples/cpp.qdoc.sample overloaded notifier
144
145
\section1 Enums, Namespaces, and Other Types
146
147
Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation:
148
\list
149
\li \l{enum-command}{\\enum}
150
\li \l{typedef-command}{\\typedef}
151
\li \l{macro-command}{\\macro}
152
\endlist
153
154
The language style for these types mention that they are an enum or a macro and
155
continues with the type description.
156
157
For enumerations, the \l{value-command}{\\value} command is for listing the
158
values. QDoc creates a table of values for the enum.
159
160
\snippet examples/cpp.qdoc.sample enums
161
162
*/
qttools
src
qdoc
qdoc
doc
qdoc-guide
qtwritingstyle-cpp.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0