| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://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 https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \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 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 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 {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. |
| */ |
| |
