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 \section1 How QDoc Works
86
87 QDoc begins by reading the configuration file you specified on the
88 command line. It stores all the variables from the configuration
89 file for later use. One of the first variables it uses is \c
90 {outputformats}. This variable tells QDoc which output generators
91 it will run. The default value is \e {HTML}, so if you don't set
92 \c {outputformats} in your configuration file, QDoc will generate
93 HTML output. That's usually what you will want anyway, but you can
94 also specify \e {DocBook} to get DocBook output instead.
95
96 Next, QDoc uses the values of the
97 \l {headerdirs-variable}
98 {headerdirs} variable and/or the \l
99 {22-qdoc-configuration-generalvariables.html#headers-variable}
100 {headers} variable to find and parse all the header files for your
101 project. QDoc does \e not scan header files for QDoc comments. It
102 parses the header files to build a master tree of all the items
103 that should be documented, in other words, the items that QDoc should find
104 QDoc comments for.
105
106 After parsing all the header files and building the master tree of
107 items to be documented, QDoc uses the value of the \l
108 {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
109 {sourcedirs} variable and/or the value of the \l
110 {22-qdoc-configuration-generalvariables.html#sources-variable}
111 {sources} variable to find and parse all the \c {.cpp} and \c
112 {.qdoc} files for your project. These are the files QDoc scans for
113 \e {QDoc comments}. Remember that a QDoc comment begins with
114 an exclamation mark: \b {/*!} .
115
116 For each QDoc comment it finds, it searches the master tree for
117 the item where the documentation belongs. Then it interprets the
118 QDoc commands in the comment and stores the interpreted commands
119 and the comment text in the tree node for the item.
120
121 Finally, QDoc traverses the master tree. For each node, if the
122 node has stored documentation, QDoc calls the output generator
123 specified by the \c {outputformats} variable to format and write
124 the documentation in the directory specified in the configuration
125 file in the \l
126 {22-qdoc-configuration-generalvariables.html#outputdir-variable}
127 {outputdir} variable.
128
129 \section1 Command Types
130
131 QDoc interprets three types of commands:
132
133 \list
134 \li \l {Topic Commands}
135 \li \l {Context Commands}
136 \li \l {Markup Commands}
137 \endlist
138
139 Topic commands identify the element you are documenting, for example
140 a C++ class, function, type, or an extra page of text
141 that doesn't map to an underlying C++ element.
142
143 Context commands tell QDoc how the element being documented
144 relates to other documented elements, for example, next and previous page
145 links, inclusion in page groups, or library modules. Context
146 commands can also provide information about the documented element
147 that QDoc can't get from the source files, for example, whether the
148 element is thread-safe, whether it is an overloaded or reimplemented function,
149 or whether it has been deprecated.
150
151 Markup commands tell QDoc how text and image elements in the
152 document should be rendered, or about the document's outline
153 structure.
154*/