path: root/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc

/****************************************************************************
**
** 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 qdoc-guide.html
    \title Getting Started with QDoc
    \nextpage Installing Clang for QDoc

    Qt uses QDoc to generate its documentation set into HTML and DITA XML
    formats. QDoc uses a set of configuration files to generate documentation
    from QDoc comments. The comments have types called
    \l{writing-topic-commands}{topics} that determine whether a comment is a
    class documentation or a property documentation. A comment may also have
    \l{writing-markup}{mark up} to enhance the layout and formatting of the
    final output.

    There are three essential materials for generating documentation with QDoc:
    \list
        \li \c QDoc binary
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist

    \note From Qt 5.11, \l{QDoc Manual}{QDoc} requires \l{http://clang.llvm.org}{Clang}
    for parsing C++ header and source files, and for parsing the function
    signatures in \l {fn-command} {\\fn} commands. See \l {Installing Clang for QDoc}
    for details.

    This section intends to cover the basic necessities for creating a
    documentation set. Additionally, the guide presents special considerations
    and options to documenting non-C++ API documentation as well as QML
    documentation. Finally, the guide will provide a sample project
    documentation and an example of a QML type documentation.

    For specific QDoc information, consult the
    \l{QDoc Manual}.
    \section1 Chapters

    \list 1
    \li \l{Installing Clang for QDoc}
    \li \l{Creating QDoc Configuration Files}
    \li \l{Writing Documentation}
    \li \l{Categories of Documentation}
        \list
        \li \l{C++ Documentation Style}
        \li \l{QML Documentation Style}
        \endlist
    \endlist

*/

/*!
    \page qdoc-guide-conf.html
    \title Creating QDoc Configuration Files
    \previouspage Installing Clang for QDoc
    \nextpage Writing Documentation
    To generate documentation, QDoc uses configuration files, with the
    \c qdocconf extension, to store configuration settings.

    The \l{The QDoc Configuration File} article covers the various configuration
    variables in greater detail.

    \section1 QDoc Configuration Files
    QDoc's configuration settings can reside in a single \e qdocconf file, but
    can also be in other qdocconf files. The \c {include(<filepath>)} command
    allows configuration files to include other configuration files.

    QDoc has two outputs, HTML documentation and documentation in DITA XML
    format. The main distinction between the two outputs is that HTML
    documentation needs to have its HTML styling information in the
    configuration files. DITA XML documentation does not, and a separate process
    can style the documentation in DITA at a later time. DITA XML is therefore
    more flexible in allowing different styles to apply to the same information.

    To run QDoc, the project configuration file is supplied as an argument.
    \code
    qdoc project.qdocconf
    \endcode

    The project configuration contains information that QDoc uses to create the
    documentation.

    \section2 Project Information

    QDoc uses the \c project information to generate the documentation.
    \code
        project = QDoc Project
        description = Sample QDoc project
    \endcode

    \target qdoc-input-output-dir
    \section2 Input and Output Directories

    Specifying the path to the source directories allow QDoc to find sources and
    generate documentation.

    \badcode
        sourcedirs = <path to source code>
        exampledirs = <path to examples directory>
        imagedirs = <path to image directory>

        sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
        headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
        examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
        examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"
    \endcode

        QDoc will process headers and sources from the ones specified in the
        \c fileextensions variable.

    Likewise, QDoc needs the path to the output directory. The \c outputformats
    variable determines the type of documentation. These variables should be
    in separate configuration files to modularize the documentation build.
    \badcode
        outputdir  =    $SAMPLE_PROJECT/doc/html
        outputformats = HTML
    \endcode

    QDoc can resolve the paths relative to the qdocconf file as well as
    environment variables.

    \note During each QDoc run, the output directory is deleted.
    \section2 Extra Files

    QDoc will output generated documentation into the directory specified in
    the  \l{Input and Output Directories}{output} directory. It is also possible
    to specify extra files that QDoc should export.

    \badcode
        HTML.extraimages = extraImage.png \
                           extraImage2.png
    \endcode

    The \c extraImage.png and the \c extraImage2.png files will be copied to the
    HTML output directory.

    \section2 Qt Help Framework Configuration

    QDoc will also export a \e {Qt Help Project} file, in a \c qhp file.
    The qhp file is then used by the \c qhelpgenerator to package the
    documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch
    file to display the documentation.

    The \l {Creating Help Project Files} article covers the configuration
    options.

    \section2 HTML Configuration

    QDoc has an HTML generator that will export a set of documentation into
    HTML files using various configuration settings. QDoc will place the
    generated documentation into the directory specified by the \c outputdir
    variable.

    \badcode
        outputformats = HTML
        outputdir =  <path to output directory>
    \endcode

    QDoc needs to know where the styles and templates for generating HTML
    are located. Typically, the templates directory contains a \c scripts,
    \c images, and a \c style directory, containing scripts and CSS files.

    The main configuration variables are:
    \badcode
        HTML.postheader
        HTML.postpostheader
        HTML.postheader
        HTML.footer

        HTML.headerstyles
        HTML.stylesheets = template/style/style.css \
                           template/style/style1.css

        HTML.scripts = template/scripts/script.js
    \endcode

    The \c{HTML.headerstyles} variable inserts the style information into the
    HTML file and the \c{HTML.stylesheets} specifies which files QDoc should
    copy into the output directory. As well, QDoc will embed the string
    in the \c postheader, \c footer, and related variables into each HTML file.

    The \l {Format-specific Configuration Variables} article outlines the usage
    of each variable.

    \section2 QDoc Index Files

    Documentation projects can link to targets in other projects by specifying
    a set of dependencies, or a set of direct paths to to index file(s) this
    project depends on. When QDoc generates documentation for a project,
    it will also generate an \c .index file containing URLs to each linkable
    entity in the project. Other projects can then define a dependency to the
    index file in order to link to the documentation within that project.

    \b {See also}: \l {depends-variable}{depends} and
                   \l {indexes-variable}{indexes}.

    \section1 Macros and Other Configurations

    Macros for substituting HTML characters exist and are helpful for generating
    specific HTML-valid characters.

    \badcode
    macro.pi.HTML         = "&Pi;"
    \endcode
    The snippet code will replace any instances of \c{\\pi} with \c &Pi; in the
    HTML file, which will appear as the Greek \pi symbol when viewed in
    browsers.

    \b {See also:} \l {macro-variable}{macro}.

    \section2 QML Additions

    QDoc is able to parse QML files for QDoc comments. QDoc will parse files
    with the QML extension, \c{.qml}, if the extension type is included in the
    \l{Input and Output Directories}{fileextensions} variable.

    Also, the generated HTML files can have a prefix and a suffix following the
    QML module name, specified in the QDoc configuration file.
    \badcode
    outputprefixes = QML
    outputprefixes.QML = uicomponents-
    outputsuffixes = QML
    outputsuffixes.QML = -tp
    \endcode

    \b {See also}: \l {outputprefixes-variable}{outputprefixes},
                   \l {outputsuffixes-variable}{outputsuffixes}.

*/

/*!
    \page qdoc-guide-writing.html
    \title Writing Documentation
    \previouspage Creating QDoc Configuration Files
    \nextpage Categories of Documentation

    \section1 QDoc Comments

    Documentation is contained within QDoc \e comments, delimited by
    \beginqdoc and \endqdoc comments. Note that these are valid comments
    in C++, QML, and JavaScript.

    Within a QDoc comment, \c {//!} is used as a single-line documentation
    comment; the comment itself and anything after it, until a newline,
    is omitted from the generated output.

    QDoc will parse C++ and QML files to look for QDoc comments. To explicitly
    omit a certain file type, omit it from the
    \l{Input and Output Directories}{configuration} file.

    \section1 QDoc Commands

    QDoc uses \e commands to retrieve information about the documentation. \c
    Topic commands determine the type of documentation element, the \c context
    commands provide hints and information about a topic, and \c markup commands
    provide information on how QDoc should format a piece of documentation.

    \target writing-topic-commands
    \section2 QDoc Topics
    Each QDoc comment must have a \e topic type. A topic distinguishes it from
    other topics. To specify a topic type, use one of the several
    \l{Topic Commands}{topic commands}.

    QDoc will collect similar topics and create a page for each one. For
    example, all the enumerations, properties, functions, and class description
    of a particular C++ class will reside in one page. A generic page is
    specified using the \l{page-command}{\\page} command and the filename is the
    argument.

    Example of topic commands:
    \list
        \li \l{enum-command}{\\enum} - for enumeration documentation
        \li \l{class-command}{\\class} - for C++ class documentation
        \li \l{qmltype-command}{\\qmltype} - for QML type documentation
        \li \l{page-command}{\\page} - for creating a page.
    \endlist

    The \l{page-command}{\\page} command is for creating articles that are not
    part of source documentation. The command can also accept two arguments: the
    file name of the article and the documentation type. The possible types are:
    \list
    \li \c howto
    \li \c overview
    \li \c tutorial
    \li \c faq
    \li \c article - \e default when there is no type
    \endlist

    \snippet examples/samples.qdocinc sample-faq

    The \l{Topic Commands} page has information on all of the available topic
    commands.

    \target writing-context
    \section2 Topic Contexts

    Context commands give QDoc a hint about the \e context of the topic. For
    example, if a C++ function is obsolete, then it should be marked obsolete
    with the \l{obsolete-command}{\\obsolete} command. Likewise,
    \l{nextpage-command}{page navigation} and \l{title-command}{page title} 
    give extra page information to QDoc.

    QDoc will create additional links or pages for these contexts. For example,
    a group is created using the \l{group-command}{\\group} command and the
    members have the \l{ingroup-command}{\\ingroup} command. The group name is
    supplied as an argument.

    The \l{Context Commands} page has a listing of all the available context
    commands.

    \target writing-markup
    \section2 Documentation Markup

    QDoc can do \e markup of text similar to other markup or
    documentation tools. QDoc can mark a section of text in \b{bold},
    when the text is marked up with the \l{b-command}{\\b} command.

    \code
        \b{This} text will be in \b{bold}.
    \endcode

    The \l{Markup Commands} page has a full listing of the available markup
    commands.

    \section1 Anatomy of Documentation

    Essentially, for QDoc to create a page, there must be some essential
    ingredients present.

    \list
        \li Assign a topic to a  QDoc comment - A comment could be a page, a
        property documentation, a class documentation, or any of the available
        \l{Topic Commands}{topic commands}.

        \li Give the topic a context - QDoc can associate certain topics to other
        pages such as associating obsolete functions when the documentation is
        marked with \l{obsolete-command}{\\obsolete}.

        \li Mark sections of the document with
        \l{Markup Commands}{markup commands} - QDoc can create layouts and
        format the documentation for the documentation.
    \endlist

    In Qt, the \l{QVector3D} class was documented with the following QDoc
    comment:
    \snippet examples/samples.qdocinc qvector3d-class

    It has a constructor, \l{QVector3D::QVector3D()}, which was documented with
    the following QDoc comment:
    \snippet examples/samples.qdocinc qvector3d-function

    The different comments may reside in different files and QDoc will collect
    them depending on their topic and their context. The resulting documentation
    from the snippets are generated into the \l{QVector3D} class documentation.

    Note that if the documentation immediately precedes the function or class
    in the source code, then it does not need to have a topic. QDoc will assume
    that the documentation above the code is the documentation for that code.

    An article is created using \l{page-command}{\\page} command. The first
    argument is the HTML file that QDoc will create. The topic is supplemented
    with context commands, the \l{title-command}{\\title} and
    \l{nextpage-command}{\\nextpage} commands. There are several other
    QDoc commands such as the \l{list-command}{\\list} command.
    \snippet examples/samples.qdocinc sample-page

    The section on \l{QDoc Topics}{topic commands} gives an overview on several
    other topic types.


*/

/*!
    \page qdoc-categories.html
    \title Categories of Documentation
    \previouspage Writing Documentation
    \brief Describes the different types such as How-To's, Tutorials, Overviews,
    Examples, and Class Documentation.

    There are several types of predefined documentation \e categories or
    \e types:
    \list
    \li How-To's
    \li Tutorial
    \li Overview
    \li Article
    \li FAQ (Frequently Asked Questions)
    \li C++ API Documentation
    \li QML Type Documentation
    \li Code Example
    \endlist

    QDoc has the ability to format a page depending on the type. Further,
    stylesheets can provide additional control on the display of each category.

    \section1 API Documentation
    QDoc excels in the creation of API documentation given a set of source code
    and documentation in QDoc comments. Specifically, QDoc is aware of Qt's
    architecture and can validate the existence of Qt C++ class, function, or
    property documentation. QDoc gives warnings and errors if it cannot
    associate a documentation with a code entity or if a code entity does not
    have documentation.

    In general, every Qt code entity such as properties, classes, methods,
    signals, and enumerations have a corresponding
    \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the
    source using C++ naming rules.

    QDoc will parse the header files (typically \c .h files) to build a tree of
    the class structures. Then QDoc will parse the source files and
    documentation files to attach documentation to the class structure.
    Afterwards, QDoc will generate a page for the class.

    \note QDoc uses the header files to inform itself about the class and will
    not properly process QDoc comments in header files.

    \section2 Language Styles

    To produce quality API documentation, the Qt API references follow a
    particular language guidelines. While the contents of this page demonstrates
    how to create API documentation, the style guidelines demonstrate how
    the reference materials follow a consistent use of language.

    \list
    \li \l{C++ Documentation Style}
    \li \l{QML Documentation Style}
    \endlist

    \keyword qml-documentation
    \section2 Documenting QML Types

    In the world of \l{Qt Quick}{QML}, there are additional entities we need to
    document such as QML signals, attached properties, and QML methods.
    Internally, they use Qt technologies, however, QML API documentation
    requires different layout and naming conventions from the Qt C++ API
    documentation.

    A list of QML related QDoc commands:
    \list
    \li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
    \li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
    \li \l{qmlbasictype-command}{\\qmlbasictype}
    \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation
    \li \l{qmlmethod-command}{\\qmlmethod}
    \li \l{qmlproperty-command}{\\qmlproperty}
    \li \l{qmlsignal-command}{\\qmlsignal}
    \li \l{inherits-command}{\\inherits}
    \li \l{qmlmodule-command}{\\qmlmodule}
    \li \l{inqmlmodule-command}{\\inqmlmodule}
    \li \l{instantiates-command}{\\instantiates}

    \endlist

    \note Remember to enable QML parsing by including the \c{*.qml} filetype in
    the \l{qdoc-input-output-dir}{fileextension} variable.

    To document a QML type, start by creating a QDoc comment that uses the
    \l{qmltype-command} {\\qmltype} command as its topic command.

    \section3 QML Parser

    If your QML type is defined in a \e qml file, document it there.
    If your QML type is represented by a C++ class, document it in the
    \e cpp file for that C++ class and include an
    \l{instantiates-command}{\\instantiates} command to specify the
    name of the C++ class. Don't document a QML type in a \e{cpp} file
    if the QML type is defined in a \e{qml} file.

    When documenting a QML type in a \e{qml} file, place each QDoc
    comment directly above the entity to which the comment applies.
    For example, place the QDoc comment containing the \e{\\qmltype}
    command (the topic comment) directly above the outer QML type in
    the \e{qml} file. Place the comment for documenting a QML property
    directly above the property declaration, and so on for QML signal
    handlers and QML methods. Note that when documenting QML
    properties in a \e{qml} file, you don't normally include the
    \e{\\qmlproperty} command as a topic command (which you must do
    when documenting QML types in \e{cpp} files), because the QML
    parser automatically associates each QDoc comment with the next
    QML declaration it parses. The same is true for QML signal handler
    and QML method comments. But it is sometimes useful to include one
    or more \e{\\qmlproperty} commands in the comment, e.g. when the
    property type is another QML type and you want the user to only
    use certain properties within that other QML type, but not all of
    them. But when documenting a property that has an alias, place the
    QDoc comment for it directly above the alias declaration. In these
    cases, the QDoc comment \e must contain a \e{\\qmlproperty}
    command, because that is the only way QDoc can know the type of
    the aliased property.

    When documenting a QML type in the \e cpp file of its
    corresponding C++ class (if it has one), you normally place each
    QDoc comment directly above the entity it documents. However, QDoc
    does not use the QML parser to parse these files (the C++ parser
    is used), so these QML QDoc comments can appear anywhere in the
    \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must
    use the QML topic commands. i.e., the \l{qmltype-command}
    {\\qmltype} command \e must appear in the QDoc comment for the
    QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e
    must appear in each QML property QDoc comment.

    \section3 QML Modules

    A QML type belongs to a \e module. The module
    may include all the related types for a platform or contain a certain
    version of \l{Qt Quick}. For example, the Qt Quick 2 QML types belong
    to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older
    types introduced in Qt 4.

    QML modules allow grouping QML types. The \l{qmltype-command}
    {\\qmltype} topic command must have an \l{inqmlmodule-command}
    {\\inqmlmodule} context command to relate the type to a QML
    module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
    command must exist in a separate \c{.qdoc} file to create the
    overview page for the module. The overview page will list the
    QML types of the QML module.

    The links to the QML types must therefore also contain the module name.
    For example, if a type called \c TabWidget is in the \c UIComponents
    module, it must be linked as \c {UIComponents::TabWidget}.

    \section3 Read-only and Internal QML Properties

    QDoc detects QML properties that are marked as \c readonly. Note that the
    property must be initialized with a value.

    \badcode
        readonly property int sampleReadOnlyProperty: 0
    \endcode

    Properties and signals that are not meant for the public interface may
    be marked with the \l{internal-command}{\\internal} command. QDoc will not
    publish the documentation in the generated outputs.

    \section1 Articles & Overviews

    Articles and overviews are a style of writing best used for providing
    summary detail on a topic or concept. It may introduce a technology or
    discuss how a concept may be applied, but without discussing exact steps
    in too much detail. However, this type of content could provide the entry
    point for readers to find instructional and reference materials that do,
    such as tutorials, examples and class documentation. An example of an
    overview might be a product page, such as a top level discussion of
    Qt Quick, individual modules, design principles, or tools.

    To signify that a document is an article, you append the article keyword
    to the \\page command:

    \snippet examples/samples.qdocinc sample-overview

    The \l{writing-topic-commands}{writing topic commands} section has a listing
    of the available \\page command arguments.

    \section1 Tutorials, How-To's, FAQ's

    Tutorials, How-To's, and FAQ's are all instructional material, in that they
    instruct or prescribe to the reader. Tutorials are content designed to guide
    the reader along a progressive learning path for a concept or technology.
    How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by
    presenting material in the form of answers to commonly asked topics.
    How-To's and FAQ's are designed for easy reference and are not necessarily
    presented in a linear progression.

    To create these types, mark the pages by providing a \c type argument to the
    \l{page-command}{\\page} command. The \c type argument is the second
    argument, with the file name being the first.
    \snippet examples/samples.qdocinc sample-faq

    The \l{writing-topic-commands}{writing topic commands} section has a listing
    of the available \\page command arguments.

    \section1 Code Examples
    Examples are an effective way to demonstrate practical usage of a given
    technology or concept. When it comes to middleware this is usually in the
    form of an application using simple code and clear explanations of what the
    code is doing. Any module, API, project, pattern etc. should have at least
    one good example.

    An example may have an accompanying tutorial. The tutorial instructs and
    describes the code, while the code example is the code content that users
    may study. Code examples may have accompanying text that are not in the
    tutorial.

    QDoc will create a page containing the example code with a description
    using the \l{example-command}{\\example} command.

    \snippet examples/samples.qdocinc sample-example

    QDoc will use the directory specified in the input
    \l{Input and Output Directories}{exampledirs} variable to find the Qt
    Project (\c .pro) file to generate the example files. The generated HTML
    will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc
    will also list all of the example code.

    \note The example's project file must be the same as the
    directory name.
*/


/*!
    \page qdoc-guide-clang.html
    \title Installing Clang for QDoc
    \previouspage Getting Started with QDoc
    \nextpage Creating QDoc Configuration Files

    QDoc uses Clang when parsing C++ files as well as function signatures in
    \l {fn-command} {\\fn} commands. Clang is part of
    \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}.
    Therefore, if you are going to build QDoc from source, you need to install
    \l{http://clang.llvm.org}{LLVM 6.0} or greater first. You can find the
    required pre-built binaries
    \l {http://releases.llvm.org/download.html}{here}.

    To build QDoc on Debian-based Linux distributions, it is sufficient to
    install the \c libclang-dev package and its dependencies. For running QDoc,
    the \c libclang package is required.

    \note On Windows, after installing the pre-built LLVM you must restart your
    build shell to ensure that LLVM's binary directory is added to the PATH
    variable. This is needed to be able to run qdoc.

    \section1 Set Clang location automatically

    The Qt build system uses the tool \c llvm-config to discover the location
    of LLVM on your system, and relies on the path to llvm-config being in
    the \c PATH environment variable to do so. \c llvm-config is commonly
    installed with LLVM and Clang on Linux systems, and also on macOS if
    LLVM is installed using Brew.

    On Windows, the installation binaries provided by LLVM do not include
    \c llvm-config. You may still have it on your system, if you have built
    LLVM yourself from source. If that is the case, and you want to let the
    build system find Clang automatically, add the path to \c llvm-config
    to your \c PATH environment variable. For example:

    \badcode
        C:\> set PATH=%PATH%;C:\[build directory]\bin\Release"
    \endcode

    Make sure to set the path to your LLVM build directory. The \c llvm-config
    executable is located in \c {bin\Release} or \c {bin\Debug}, reflecting the
    build version.

    \section1 Specify Clang location manually

    If \c llvm-config is not in your \c PATH environment variable, or not
    installed on your system, you can still build QDoc, by manually setting the
    environment variable \c LLVM_INSTALL_DIR to point to the directory where
    the Clang libraries are installed. This directory should be the top level
    directory. For example, on a Linux or macOS system with LLVM installed to
    \c /usr/llvm:

    \badcode
        $ export LLVM_INSTALL_DIR=/usr/llvm
    \endcode

    Debian-based Linux distributions usually offer multiple versions of the
    \c libclang packages, such as \c libclang-<VERSION>. In this case,
    \c LLVM_INSTALL_DIR should contain \c /usr/lib/clang/<VERSION> .

    On a Windows system with LLVM installed to \c {C:\Program Files\LLVM}:

    \badcode
        C:\> set LLVM_INSTALL_DIR=C:\Program Files\LLVM
    \endcode
*/