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

/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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 qdoc-guide.html
    \title Getting Started with QDoc
    \nextpage Creating QDoc Configuration Files

    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

    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{Table of Contents}{QDoc Manual}.
    \section1 Chapters

    \list 1
    \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
    \li \l{Configuration File Example}
    \li \l{QML Documentation Example}
    \endlist

*/

/*!
    \page qdoc-guide-conf.html
    \title Creating QDoc Configuration Files
    \previouspage Getting Started with 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.

    \code
        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.
    \code
        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.

    \code
        extraimages.HTML = 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 \l{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.

    \code
        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.

    \code
        HTML.templatedir = <path to templates>
    \endcode

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

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

        HTML.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 {HTML Specific Configuration Variables} article outlines the usage
    of each variable.

    \section2 DITA XML Configuration

    DITA XML output is enabled using the \c outputformats variable. Unlike HTML
    documentation, QDoc does not need HTML style templates for generating
    documentation in DITA XML format.

    \code
        outputformats = DITAXML
        outputdir
    \endcode

    \section2 Qt Index Reference
    Documentation projects can link to Qt APIs and other articles by specifying
    the path to the \c qt.index file. When qdoc generates the Qt Reference
    Documentation, it will also generate an index file, containing the URLs to
    the articles. Other projects can use the links in the index file so that
    they can link to other articles and API documentation within Qt.

    \code
        indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index
    \endcode
    It is possible to specify multiple index files from several projects.

    \section1 Macros and Other Configurations

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

    \code
    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.

    \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, specified in the QDoc
    configuration file.
    \code
    outputprefixes = QML
    outputprefixes.QML = uicomponents-
    \endcode
    The outputprefixes will, for example, prefix QML type HTML filenames.
    \code
    files:
        uicomponents-button.html
        uicomponents-scrollbar.html
    \endcode

*/

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

    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
    \nextpage Configuration File Example
    \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 \l{QML Elements} 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}.

    The \l{componentset}{UIComponents} example demonstrates proper usage of
    QDoc commands to document QML types and QML modules.

    \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.

    \code
        readonly property int sampleReadOnlyProperty: 0
    \endcode
    For example, the example \l{TabWidget} type has a fictitious read-only
    property \c sampleReadOnlyProperty. Its declaration has the \c readonly
    identifier and it has an initial value.

    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. For reference, view QDoc's generated
    page for the \l{UI Components: Tab Widget Example}{Tab Widget} example.

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

/*!
    \example config
    \title Configuration File Example
    \previouspage Categories of Documentation
    \brief configuration files for the QDoc Manual and QDoc Guide

    The QDoc Manual uses these \c qdocconf files to generate the QDoc Guide and
    the \l{Table of Contents}{QDoc Manual}.

    \note The configuration files are similar to the Qt Reference Documentation
    and the QDoc Manual do not use all of the variables. The variables are
    included to demonstrate a full project scenario.

    \section1 Macros and other Definitions
    \list
    \li \l{config/compat.qdocconf}
    \li \l{config/macros.qdocconf}
    \li \l{config/qt-cpp-ignore.qdocconf}
    \li \l{config/qt-defines.qdocconf}
    \endlist

    QDoc allows macros to help with aliasing and for inputting special HTML
    characters within the documentation. Macros are a form of workarounds if
    QDoc is unable to resolve formatting issues such as when QDoc should
    disregard QDoc comments in documentation paragraphs.

    QDoc is also aware of the common C++ and Qt preprocessors and can decide
    which documentation to generate according to the definitions in the
    configuration files.

    \section1 Project Information
    \list
    \li \l{config/qdoc-online.qdocconf}
    \li \l{config/qdoc.qdocconf}
    \li \l{config/qdoc-project.qdocconf}
    \endlist

    These configuration files dictate how QDoc will generate the project.
    Depending which configuration file QDoc processes, the formatting and the
    information about the project will be different. If QDoc processes
    \c{qdoc-online.qdocconf}, QDoc will generate the HTML version of the manual
    will have the style suitable for online viewing.

    Additionally, the settings for creating the
    \l{The Qt Help Framework}{Qt Help File} is in the configuration.

    \note The project file uses variables used during Qt's
    \l{Configuration Options for Qt}{configuration} step.

    \section1 HTML Styles
    \list
    \li \l{config/qt-html-default-styles.qdocconf}
    \li \l{config/qt-html-online-styles.qdocconf}
    \li \l{config/qt-html-templates-online.qdocconf}
    \li \l{config/qt-html-templates.qdocconf}
    \endlist

    These files indicate which styles QDoc should use for the HTML formats.
    Typically, there are two templates, one for online viewing and one for
    offline. Qt Creator is able to fit more content in a page with the offline
    template. The templates store HTML information as strings and QDoc will copy
    the template to each HTML page.

    \section1 Project File
    \list
    \li \l{config/config.pro}
    \endlist

    Every example page (such as this one) needs a Qt project file. QDoc will
    use the project file to determine which files are part of the example. QDoc
    will then create a page listing all the files that are part of the example.

    \note the directory name of the example and the name of the project file
    must match. The example directory is found using the
    \l{qdoc-input-output-dir}{exampledirs} variable.
*/