diff options
Diffstat (limited to 'src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc')
| -rw-r--r-- | src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc new file mode 100644 index 000000000..0aeb715c9 --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc @@ -0,0 +1,299 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 01-qdoc-manual.html + \previouspage QDoc Manual + \nextpage Command Index + + \title Introduction to QDoc + + QDoc is a tool used by Qt Developers to generate documentation for + software projects. It works by extracting \e {QDoc comments} from + project source files and then formatting these comments as HTML + pages or DocBook XML documents. QDoc finds QDoc comments in \c + {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc + comments in \c {.h} files. A QDoc comment always begins with an + exclamation mark (\b{!})). For example: + + \badcode * + /\1! + \class QObject + \brief The QObject class is the base class of all Qt objects. + + \ingroup objectmodel + + \reentrant + + QObject is the heart of the Qt \l{Object Model}. The + central feature in this model is a very powerful mechanism + for seamless object communication called \l{signals and + slots}. You can connect a signal to a slot with connect() + and destroy the connection with disconnect(). To avoid + never ending notification loops you can temporarily block + signals with blockSignals(). The protected functions + connectNotify() and disconnectNotify() make it possible to + track connections. + + QObjects organize themselves in \l {Object Trees & + Ownership} {object trees}. When you create a QObject with + another object as parent, the object will automatically + add itself to the parent's \c children() list. The parent + takes ownership of the object. It will automatically + delete its children in its destructor. You can look for an + object by name and optionally type using findChild() or + findChildren(). + + Every object has an objectName() and its class name can be + found via the corresponding metaObject() (see + QMetaObject::className()). You can determine whether the + object's class inherits another class in the QObject + inheritance hierarchy by using the \c inherits() function. + + .... + \1/ + \endcode + + From the QDoc comment above, QDoc generates the HTML \l {QObject} + {QObject class reference} page. + + This manual explains how to use the QDoc commands in QDoc comments + to embed good documentation in your source files. It also explains + how to make a \l {The QDoc Configuration File} {QDoc configuration + file}, which you will pass to QDoc on the command line. + + \section1 Running QDoc + + The name of the QDoc program is \c {qdoc}. To run QDoc from the + command line, give it the name of a configuration file: + + \quotation + \c {$ ../../bin/qdoc ./config.qdocconf} + \endquotation + + QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc + Configuration File} {QDoc configuration file}. The configuration + file is where you tell QDoc where to find the project source + files, header files, and \c {.qdoc} files. It is also where you + tell QDoc what kind of output to generate (HTML, DocBook XML...), + and where to put the generated documentation. The configuration + file also contains other information for QDoc. + + See \l{The QDoc Configuration File} for instructions on how to + set up a QDoc configuration file. + + \section2 Running QDoc in Single Execution Mode + + Beginning with Qt 5.5, a new way to run QDoc is available that + reduces the time it takes to generate the Qt5 documentation by as + much as 90%. The new way to run QDoc is \e{single execution} mode. + Single execution mode is not currently available in the Qt5 build + system, which still uses the \e {standard} mode. Single execution + mode is only available when you run QDoc yourself, which you will + want to do often as you document your module and integrate your + documentation with the other Qt modules. + + To run QDoc in single execution mode, add \c {-single-exec} to the + command line and pass QDoc a master \c qdocconf file that is + simply a list of file paths for qdocconf files of all the Qt5 + modules. For example: + + \code + /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 + \endcode + + The qdocconf file, \c {master.qdocconf}, just lists the qdocconf files for all the Qt5 modules to be processed: + + \badcode + /Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf + /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf + /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf + /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf + /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf + /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf + /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf + /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf + /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf + /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf + /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf + /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf + /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf + /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf + /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf + /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf + /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf + /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf + /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf + /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf + /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf + /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf + /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf + /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf + /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf + /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf + /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf + /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf + /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf + /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf + /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf + /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf + /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf + /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf + /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf + /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf + \endcode + + \section3 Why Standard Mode Is Slow + + Currently, the Qt5 build system does not use QDoc's \e {single + execution} mode for generating the Qt5 documentation. It runs QDoc + in the \e {standard} mode. The standard mode was came about + because it was the easiest way to get convert the Qt4 QDoc to + handle the modularization of Qt in Qt5. In Qt4, QDoc ran once over + all the Qt4 sources to generate the HTML documentation for Qt. + While generating the Qt documentation, Qt4 QDoc also generated an + \e {index file} for Qt. That index file was meant to be used as + input to subsequent QDoc runs for generating HTML documentation + for other software libraries/products that were based on Qt. The + Qt index file allowed QDoc to link documentation written for those + other libraries/products to the Qt4 documentation. + + When Qt5 came along, Qt was divided into modules. Since then, + many new modules have been added to Qt. As of version 5.5, there + are over 40 separate modules in Qt5, each with its own + documentation that links to (depends on) the documentation of + other Qt modules. + + In \e {standard mode}, QDoc runs twice for each module. The first + QDoc run for a particular Qt module, parses all the module's + source files and then uses the information to generate the + module's index file. It is called the \e{prepare phase} because + it \e prepares the module's index file. The second QDoc run for + the module also parses all the module's source files and then + generates the module's documentation pages. This is called the \e + {generate phase} because it generates the module's documentation. + + The module's documentation will likely contain HTML links to the + documentation of one or more of the other Qt modules. For example, + most Qt5 modules contain links to documentation in QtCore. When a + Qt module contains links into the documentation of other Qt + module's, that module is said to depend on those other Qt modules. + Hence when QDoc runs the \e {generate phase} for that module, it + must also load the index files for those modules so it can create + those links. + + Hence, when the Qt build system generates the Qt documentation, it + first runs QDoc once for each module to perform the \e {prepare + phase} to generate all the index files. Then it runs QDoc once for + each module to perform the \e {generate phase}, where it uses the + dependent index files to generate the module's documentation, + including any cross-module links it finds. Each execution of + QDoc, both \e {prepare phase} and \e {generate phase}, parses + all the source files that are included in the module, and in the + \e {generate phase} also parses the index files for the dependent + modules. Nothing is retained or retainable between QDoc runs. + + \section3 Why Single Execution Mode Is Much Faster + + As the name implies, single execution mode uses a single QDoc + process to generate all the Qt5 documentation. The single QDoc + process still performs a \e{prepare phase} for each module and + then a \e{generate phase} for each module, but there are a few + differences. It begins by reading the master qdocconf file. Then + it reads each qdocconf file in the master list and performs the + \e{prepare phase} for each module. During the \e{prepare phase}, + all the source files for the module are parsed to build a syntax + tree for the module. The module's index file is then generated, + although QDoc will not re-read the index files in the \e{generate + phase}. The important difference here is that the module's syntax + tree is retained after the index file is generated, so that after + the \e{prepare phase} has been run for all the modules, QDoc still + has all the syntax trees it built. + + QDoc then processes each module again for the \e{generate phase}. + But now QDoc doesn't need to re-parse each module's source files, + because the module's syntax tree is still in memory. Nor does QDoc + need to re-read the index files for the dependent modules, again + because it still has the syntax trees for those modules in memory. + It remains only to traverse each module's syntax tree to generate + the documentation pages. + + Hence, QDoc parses each source file once and only once and doesn't + need to read index files. This is what makes single execution mode + much faster than the standard mode. It is anticipated that the Qt + build system will eventually run QDoc in single execution mode. + However, changes to the master qdocconf file might be required, so + the method described above for running QDoc in single execution + mode might have to change, watch this space for updates. + + \section1 How QDoc Works + + QDoc begins by reading the configuration file you specified on the + command line. It stores all the variables from the configuration + file for later use. One of the first variables it uses is \c + {outputformats}. This variable tells QDoc which output generators + it will run. The default value is \e {HTML}, so if you don't set + \c {outputformats} in your configuration file, QDoc will generate + HTML output. That's usually what you will want anyway, but you can + also specify \e {DocBook} to get DocBook output instead. + + Next, QDoc uses the values of the + \l {headerdirs-variable} + {headerdirs} variable and/or the \l + {22-qdoc-configuration-generalvariables.html#headers-variable} + {headers} variable to find and parse all the header files for your + project. QDoc does \e not scan header files for QDoc comments. It + parses the header files to build a master tree of all the items + that should be documented, in other words, the items that QDoc should find + QDoc comments for. + + After parsing all the header files and building the master tree of + items to be documented, QDoc uses the value of the \l + {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} + {sourcedirs} variable and/or the value of the \l + {22-qdoc-configuration-generalvariables.html#sources-variable} + {sources} variable to find and parse all the \c {.cpp} and \c + {.qdoc} files for your project. These are the files QDoc scans for + \e {QDoc comments}. Remember that a QDoc comment begins with + an exclamation mark: \b {/*!} . + + For each QDoc comment it finds, it searches the master tree for + the item where the documentation belongs. Then it interprets the + QDoc commands in the comment and stores the interpreted commands + and the comment text in the tree node for the item. + + Finally, QDoc traverses the master tree. For each node, if the + node has stored documentation, QDoc calls the output generator + specified by the \c {outputformats} variable to format and write + the documentation in the directory specified in the configuration + file in the \l + {22-qdoc-configuration-generalvariables.html#outputdir-variable} + {outputdir} variable. + + \section1 Command Types + + QDoc interprets three types of commands: + + \list + \li \l {Topic Commands} + \li \l {Context Commands} + \li \l {Markup Commands} + \endlist + + Topic commands identify the element you are documenting, for example + a C++ class, function, type, or an extra page of text + that doesn't map to an underlying C++ element. + + Context commands tell QDoc how the element being documented + relates to other documented elements, for example, next and previous page + links, inclusion in page groups, or library modules. Context + commands can also provide information about the documented element + that QDoc can't get from the source files, for example, whether the + element is thread-safe, whether it is an overloaded or reimplemented function, + or whether it has been deprecated. + + Markup commands tell QDoc how text and image elements in the + document should be rendered, or about the document's outline + structure. +*/ + |