path: root/src/tools/qdoc/doc/qdoc-manual-intro.qdoc

/****************************************************************************
**
** 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.
*/