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
qdoc-manual-intro.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 01-qdoc-manual.html
6
\previouspage QDoc Manual
7
\nextpage Command Index
8
9
\title Introduction to QDoc
10
11
QDoc is a tool used by Qt Developers to generate documentation for
12
software projects. It works by extracting \e {QDoc comments} from
13
project source files and then formatting these comments as HTML
14
pages or DocBook XML documents. QDoc finds QDoc comments in \c
15
{.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc
16
comments in \c {.h} files. A QDoc comment always begins with an
17
exclamation mark (\b{!})). For example:
18
19
\badcode *
20
/\1!
21
\class QObject
22
\brief The QObject class is the base class of all Qt objects.
23
24
\ingroup objectmodel
25
26
\reentrant
27
28
QObject is the heart of the Qt \l{Object Model}. The
29
central feature in this model is a very powerful mechanism
30
for seamless object communication called \l{signals and
31
slots}. You can connect a signal to a slot with connect()
32
and destroy the connection with disconnect(). To avoid
33
never ending notification loops you can temporarily block
34
signals with blockSignals(). The protected functions
35
connectNotify() and disconnectNotify() make it possible to
36
track connections.
37
38
QObjects organize themselves in \l {Object Trees &
39
Ownership} {object trees}. When you create a QObject with
40
another object as parent, the object will automatically
41
add itself to the parent's \c children() list. The parent
42
takes ownership of the object. It will automatically
43
delete its children in its destructor. You can look for an
44
object by name and optionally type using findChild() or
45
findChildren().
46
47
Every object has an objectName() and its class name can be
48
found via the corresponding metaObject() (see
49
QMetaObject::className()). You can determine whether the
50
object's class inherits another class in the QObject
51
inheritance hierarchy by using the \c inherits() function.
52
53
....
54
\1/
55
\endcode
56
57
From the QDoc comment above, QDoc generates the HTML \l {QObject}
58
{QObject class reference} page.
59
60
This manual explains how to use the QDoc commands in QDoc comments
61
to embed good documentation in your source files. It also explains
62
how to make a \l {The QDoc Configuration File} {QDoc configuration
63
file}, which you will pass to QDoc on the command line.
64
65
\section1 Running QDoc
66
67
The name of the QDoc program is \c {qdoc}. To run QDoc from the
68
command line, give it the name of a configuration file:
69
70
\quotation
71
\c {$ ../../bin/qdoc ./config.qdocconf}
72
\endquotation
73
74
QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
75
Configuration File} {QDoc configuration file}. The configuration
76
file is where you tell QDoc where to find the project source
77
files, header files, and \c {.qdoc} files. It is also where you
78
tell QDoc what kind of output to generate (HTML, DocBook XML...),
79
and where to put the generated documentation. The configuration
80
file also contains other information for QDoc.
81
82
See \l{The QDoc Configuration File} for instructions on how to
83
set up a QDoc configuration file.
84
85
\section2 Running QDoc in Single Execution Mode
86
87
Beginning with Qt 5.5, a new way to run QDoc is available that
88
reduces the time it takes to generate the Qt5 documentation by as
89
much as 90%. The new way to run QDoc is \e{single execution} mode.
90
Single execution mode is not currently available in the Qt5 build
91
system, which still uses the \e {standard} mode. Single execution
92
mode is only available when you run QDoc yourself, which you will
93
want to do often as you document your module and integrate your
94
documentation with the other Qt modules.
95
96
To run QDoc in single execution mode, add \c {-single-exec} to the
97
command line and pass QDoc a master \c qdocconf file that is
98
simply a list of file paths for qdocconf files of all the Qt5
99
modules. For example:
100
101
\code
102
/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec
103
\endcode
104
105
The qdocconf file, \c {master.qdocconf}, just lists the qdocconf files for all the Qt5 modules to be processed:
106
107
\badcode
108
/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
109
/Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
110
/Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
111
/Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
112
/Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
113
/Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
114
/Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
115
/Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
116
/Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
117
/Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
118
/Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
119
/Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
120
/Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
121
/Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
122
/Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
123
/Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
124
/Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
125
/Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
126
/Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
127
/Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
128
/Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
129
/Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
130
/Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
131
/Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
132
/Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
133
/Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
134
/Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
135
/Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
136
/Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
137
/Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
138
/Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
139
/Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
140
/Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
141
/Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
142
/Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
143
/Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf
144
\endcode
145
146
\section3 Why Standard Mode Is Slow
147
148
Currently, the Qt5 build system does not use QDoc's \e {single
149
execution} mode for generating the Qt5 documentation. It runs QDoc
150
in the \e {standard} mode. The standard mode was came about
151
because it was the easiest way to get convert the Qt4 QDoc to
152
handle the modularization of Qt in Qt5. In Qt4, QDoc ran once over
153
all the Qt4 sources to generate the HTML documentation for Qt.
154
While generating the Qt documentation, Qt4 QDoc also generated an
155
\e {index file} for Qt. That index file was meant to be used as
156
input to subsequent QDoc runs for generating HTML documentation
157
for other software libraries/products that were based on Qt. The
158
Qt index file allowed QDoc to link documentation written for those
159
other libraries/products to the Qt4 documentation.
160
161
When Qt5 came along, Qt was divided into modules. Since then,
162
many new modules have been added to Qt. As of version 5.5, there
163
are over 40 separate modules in Qt5, each with its own
164
documentation that links to (depends on) the documentation of
165
other Qt modules.
166
167
In \e {standard mode}, QDoc runs twice for each module. The first
168
QDoc run for a particular Qt module, parses all the module's
169
source files and then uses the information to generate the
170
module's index file. It is called the \e{prepare phase} because
171
it \e prepares the module's index file. The second QDoc run for
172
the module also parses all the module's source files and then
173
generates the module's documentation pages. This is called the \e
174
{generate phase} because it generates the module's documentation.
175
176
The module's documentation will likely contain HTML links to the
177
documentation of one or more of the other Qt modules. For example,
178
most Qt5 modules contain links to documentation in QtCore. When a
179
Qt module contains links into the documentation of other Qt
180
module's, that module is said to depend on those other Qt modules.
181
Hence when QDoc runs the \e {generate phase} for that module, it
182
must also load the index files for those modules so it can create
183
those links.
184
185
Hence, when the Qt build system generates the Qt documentation, it
186
first runs QDoc once for each module to perform the \e {prepare
187
phase} to generate all the index files. Then it runs QDoc once for
188
each module to perform the \e {generate phase}, where it uses the
189
dependent index files to generate the module's documentation,
190
including any cross-module links it finds. Each execution of
191
QDoc, both \e {prepare phase} and \e {generate phase}, parses
192
all the source files that are included in the module, and in the
193
\e {generate phase} also parses the index files for the dependent
194
modules. Nothing is retained or retainable between QDoc runs.
195
196
\section3 Why Single Execution Mode Is Much Faster
197
198
As the name implies, single execution mode uses a single QDoc
199
process to generate all the Qt5 documentation. The single QDoc
200
process still performs a \e{prepare phase} for each module and
201
then a \e{generate phase} for each module, but there are a few
202
differences. It begins by reading the master qdocconf file. Then
203
it reads each qdocconf file in the master list and performs the
204
\e{prepare phase} for each module. During the \e{prepare phase},
205
all the source files for the module are parsed to build a syntax
206
tree for the module. The module's index file is then generated,
207
although QDoc will not re-read the index files in the \e{generate
208
phase}. The important difference here is that the module's syntax
209
tree is retained after the index file is generated, so that after
210
the \e{prepare phase} has been run for all the modules, QDoc still
211
has all the syntax trees it built.
212
213
QDoc then processes each module again for the \e{generate phase}.
214
But now QDoc doesn't need to re-parse each module's source files,
215
because the module's syntax tree is still in memory. Nor does QDoc
216
need to re-read the index files for the dependent modules, again
217
because it still has the syntax trees for those modules in memory.
218
It remains only to traverse each module's syntax tree to generate
219
the documentation pages.
220
221
Hence, QDoc parses each source file once and only once and doesn't
222
need to read index files. This is what makes single execution mode
223
much faster than the standard mode. It is anticipated that the Qt
224
build system will eventually run QDoc in single execution mode.
225
However, changes to the master qdocconf file might be required, so
226
the method described above for running QDoc in single execution
227
mode might have to change, watch this space for updates.
228
229
\section1 How QDoc Works
230
231
QDoc begins by reading the configuration file you specified on the
232
command line. It stores all the variables from the configuration
233
file for later use. One of the first variables it uses is \c
234
{outputformats}. This variable tells QDoc which output generators
235
it will run. The default value is \e {HTML}, so if you don't set
236
\c {outputformats} in your configuration file, QDoc will generate
237
HTML output. That's usually what you will want anyway, but you can
238
also specify \e {DocBook} to get DocBook output instead.
239
240
Next, QDoc uses the values of the
241
\l {headerdirs-variable}
242
{headerdirs} variable and/or the \l
243
{22-qdoc-configuration-generalvariables.html#headers-variable}
244
{headers} variable to find and parse all the header files for your
245
project. QDoc does \e not scan header files for QDoc comments. It
246
parses the header files to build a master tree of all the items
247
that should be documented, in other words, the items that QDoc should find
248
QDoc comments for.
249
250
After parsing all the header files and building the master tree of
251
items to be documented, QDoc uses the value of the \l
252
{22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
253
{sourcedirs} variable and/or the value of the \l
254
{22-qdoc-configuration-generalvariables.html#sources-variable}
255
{sources} variable to find and parse all the \c {.cpp} and \c
256
{.qdoc} files for your project. These are the files QDoc scans for
257
\e {QDoc comments}. Remember that a QDoc comment begins with
258
an exclamation mark: \b {/*!} .
259
260
For each QDoc comment it finds, it searches the master tree for
261
the item where the documentation belongs. Then it interprets the
262
QDoc commands in the comment and stores the interpreted commands
263
and the comment text in the tree node for the item.
264
265
Finally, QDoc traverses the master tree. For each node, if the
266
node has stored documentation, QDoc calls the output generator
267
specified by the \c {outputformats} variable to format and write
268
the documentation in the directory specified in the configuration
269
file in the \l
270
{22-qdoc-configuration-generalvariables.html#outputdir-variable}
271
{outputdir} variable.
272
273
\section1 Command Types
274
275
QDoc interprets three types of commands:
276
277
\list
278
\li \l {Topic Commands}
279
\li \l {Context Commands}
280
\li \l {Markup Commands}
281
\endlist
282
283
Topic commands identify the element you are documenting, for example
284
a C++ class, function, type, or an extra page of text
285
that doesn't map to an underlying C++ element.
286
287
Context commands tell QDoc how the element being documented
288
relates to other documented elements, for example, next and previous page
289
links, inclusion in page groups, or library modules. Context
290
commands can also provide information about the documented element
291
that QDoc can't get from the source files, for example, whether the
292
element is thread-safe, whether it is an overloaded or reimplemented function,
293
or whether it has been deprecated.
294
295
Markup commands tell QDoc how text and image elements in the
296
document should be rendered, or about the document's outline
297
structure.
298
*/
qttools
src
qdoc
qdoc
doc
qdoc-manual-intro.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0