diff options
Diffstat (limited to 'src/tools/qdoc/doc/qdoc-manual-intro.qdoc')
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual-intro.qdoc | 325 |
1 files changed, 0 insertions, 325 deletions
diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc deleted file mode 100644 index 84f9416843..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc +++ /dev/null @@ -1,325 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 01-qdoc-manual.html - \contentspage QDoc Manual - \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 DITA 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: - - \code - / *! - \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. - - .... - * / - \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, DITA 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/qtimageformats/src/imageformats/doc/qtimageformats.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 thinks. - - 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 memry. - 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 {DITAXML} to get DITA XML 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. -*/ - |