path: root/src/qdoc/qdoc/doc/qdoc-manual-topiccmds.qdoc

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page 13-qdoc-commands-topics.html
    \previouspage Command Index
    \nextpage Context Commands

    \title Topic Commands

    A topic command tells QDoc which source code element is being
    documented. Some topic commands allow you to create documentation
    pages that aren't tied to any underlying source code element.

    When QDoc processes a QDoc comment, it tries to connect the
    comment to an element in the source code by first looking for a
    topic command that names the source code element. If there is no
    topic command, QDoc tries to connect the comment to the source
    code element that immediately follows the comment. If it can't do
    either of these and if there is no topic command that indicates
    the comment does not have an underlying source code element (e.g.
    \l{page-command} {\\page}), then the comment is discarded.

    \target topic argument

    The name of the entity being documented is usually the only
    argument for a topic command. Use the complete name. Sometimes
    there can be a second parameter in the argument. See e.g. \l
    {page-command} {\\page}.

    \code
        \enum QComboBox::InsertPolicy
    \endcode

    The \l {fn-command} {\\fn} command is a special case. For the \l
    {fn-command} {\\fn} command, use the function's signature
    including the class qualifier.

    \code
        \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
    \endcode

    A topic command can appear anywhere in a comment but must stand
    alone on its own line. It is good practice is to let the topic command
    be the first line of the comment. If the argument spans several
    lines, make sure that each line (except the last one) is ended
    with a backslash. Moreover, QDoc counts parentheses, which means
    that if it encounters a '(' it considers everything until the
    closing ')' as its argument.

    If a topic command is repeated with different arguments, the
    same documentation will appear for both the units.

    \badcode *
    /\1!
        \fn void PreviewWindow::setWindowFlags()
        \fn void ControllerWindow::setWindowFlags()

        Sets the widgets flags using the QWidget::setWindowFlags()
        function.

        Then runs through the available window flags, creating a text
        that contains the names of the flags that matches the flags
        parameter, displaying the text in the widgets text editor.
    \1/
    \endcode

    The \c PreviewWindow::setWindowFlags() and \c
    ControllerWindow::setWindowFlags() functions will get the same
    documentation.

    \section2 Nomenclature for files generated by topic commands

    For many topic commands, such as \l {page-command}{\\page}, QDoc
    generates a file when processing the documentation.

    QDoc normalizes the name of each file before writing it to disk.
    The following operations are performed:

    \list
        \li All sequences of non alphanumeric characters are replaced with a hyphen, '-'.
        \li All uppercase letters are replaced with their lowercase equivalent.
        \li All trailing hyphens are removed.
    \endlist

    For example, the following command generates a file named
    \c{this-generates-a-file-and-writes-it-to-disk.html}:

    \badcode
    \page this_generates_a_file_(and_writes_it_to_DISK)-.html
    \endcode

    As the example shows, the name that is given to the file in the
    command might differ from the name of the actual file that is
    written to disk.

    \section3 Prefixes and Suffixes for generated files

    When QDoc generates a file, it may add a prefix, a suffix, or both,
    depending on the element that the file will document.

    The table below shows what those prefixes and suffixes are for
    various elements.

    \table
        \header
            \li Element
            \li Prefix
            \li Suffix
            \li Command
        \row
            \li QML Modules
            \li None
            \li "-qmlmodule"
            \li \l {qmlmodule-command}{\\qmlmodule}
        \row
            \li Modules
            \li None
            \li "-module"
            \li \l {module-command}{\\module}
        \row
            \li Examples
            \li The project name, as given by the \l
            {project-variable}{project configuration variable},
            followed by a hyphen.
            \li "-example"
            \li \l {example-command}{\\example}
        \row
            \li QML Types
            \li The output prefix for QML, as given by the \l
            {outputprefixes-variable}{outputprefixes configuration
            variable}.

            If the module that contains this type is known to QDoc,
            the module name is added as a prefix, followed by the QML
            output suffix, as defined by the \l
            {outputsuffixes-variable}{outputsuffixes configuration
            variable} and a hyphen.
            \li None
            \li \l {qmltype-command}{\\qmltype}
    \endtable

    \target class-command
    \section1 \\class

    The \\class command is for documenting a C++ \e class, a C/C++
    \e struct, or a \e union. The argument is the complete, qualified
    name of the class. The command tells QDoc that a class is part of
    the public API, and lets you enter a detailed description.

    \badcode *
    /\1!
        \class QMap::iterator
        \inmodule QtCore

        \brief The QMap::iterator class provides an STL-style
        non-const iterator for QMap and QMultiMap.

        QMap features both \l{STL-style iterators} and
        \l{Java-style iterators}. The STL-style iterators ...
    \1/
    \endcode

    The HTML documentation for the named class is written to a
    \c{.html} file named from the class name, in lower case, and with
    the double colon qualifiers replaced with '-'. For example, the
    documentation for the \c QMap::iterator class is written to \c
    qmap-iterator.html.

    The file contains the class description from the \\class comment,
    plus the documentation generated from QDoc comments for all the
    class members: a list of the class's types, properties,
    functions, signals, and slots.

    In addition to the detailed description of the class, the \\class
    comment typically contains an \l {inmodule-command} {\\inmodule}
    command, as well as a \l {brief-command} {\\brief} description.
    Here is a very simple example:

    \badcode *
    /\1!
        \class PreviewWindow
        \inmodule CustomWidgets
        \brief The PreviewWindow class is a custom widget.
               displaying the names of its currently set
               window flags in a read-only text editor.

        \ingroup miscellaneous

        The PreviewWindow class inherits QWidget. The widget
        displays the names of its window flags set with the \l
        {function} {setWindowFlags()} function. It is also
        provided with a QPushButton that closes the window.

        ...

        \sa QWidget
    \1/
    \endcode

    The way QDoc renders this \\class depends on your \c {style.css}
    file.

    \target enum-command
    \section1 \\enum

    The \\enum command is for documenting a C++ enum type. The
    argument is the full name of the enum type.

    The enum values are documented in the \\enum comment using the \l
    {value-command} {\\value} command. If an enum value is not
    documented with \\value, QDoc emits a warning. These warnings can
    be avoided using the \l {omitvalue-command} {\\omitvalue} command
    to tell QDoc that an enum value should not be documented. The enum
    documentation will be included on the class reference page, header
    file page, or namespace page where the enum type is defined. For
    example, consider the enum type \c {Corner} in the Qt namespace:

    \code
        enum Corner {
            TopLeftCorner = 0x00000,
            TopRightCorner = 0x00001,
            BottomLeftCorner = 0x00002,
            BottomRightCorner = 0x00003
        #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
            ,TopLeft = TopLeftCorner,
            TopRight = TopRightCorner,
            BottomLeft = BottomLeftCorner,
            BottomRight = BottomRightCorner
        #endif
        };
    \endcode

    This enum can be cocumented this way:

    \badcode *
    /\1!
        \enum Qt::Corner

        This enum type specifies a corner in a rectangle:

        \value TopLeftCorner
               The top-left corner of the rectangle.
        \value TopRightCorner
               The top-right corner of the rectangle.
        \value BottomLeftCorner
               The bottom-left corner of the rectangle.
        \value BottomRightCorner
               The bottom-right corner of the rectangle.

        \omitvalue TopLeft
        \omitvalue TopRight
        \omitvalue BottomLeft
        \omitvalue BottomRight
                   Bottom-right (omitted; not documented).
    \1/
    \endcode

    Note the inclusion of the namespace qualifier.

    See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.

    \target example-command
    \section1 \\example

    The \\example command is for documenting an example. The argument
    is the example's path relative to one of the paths listed in the
    \l {exampledirs-variable} {exampledirs} variable in the QDoc
    configuration file.

    The documentation page will be output to \c {modulename-path-to-example}.html.
    QDoc will add a list of all the example's source and images files at the end
    of the page, unless \l {noautolist-command}{\\noautolist} command is used or
    the configuration variable \l {url.examples-variable}{url.examples} is defined
    for the project.

    For example, if \l {exampledirs-variable} {exampledirs} contains
    \c $QTDIR/examples/widgets/imageviewer, then

    \badcode *
    /\1!
        \example widgets/imageviewer
        \title ImageViewer Example
        \subtitle

        The example shows how to combine QLabel and QScrollArea
        to display an image.

        ...
    \1/
    \endcode

    \b {See also:} \l {noautolist-command}{\\noautolist},
                   \l {url.examples-variable}{url.examples},
                   \l {meta-command}{\\meta}

    \target externalpage-command
    \section1 \\externalpage

    The \\externalpage command assigns a title to an external URL.

    \badcode *
    /\1!
        \externalpage http://doc.qt.io/
        \title Qt Documentation Site
    \1/
    \endcode

    This allows you to include a link to the external page in your
    documentation this way:

    \badcode *
    /\1!
        At the \l {Qt Documentation Site} you can find the latest
        documentation for Qt, Qt Creator, the Qt SDK and much more.
    \1/
    \endcode

    To achieve the same result without using the \\externalpage
    command, you would have to hard-code the address into your
    documentation:

    \badcode *
    /\1!
        At the \l {http://doc.qt.io/}{Qt Documentation Site}
        you can find the latest documentation for Qt, Qt Creator, the Qt SDK
        and much more.
    \1/
    \endcode

    The \\externalpage command makes it easier to maintain the
    documentation. If the address changes, you only need to change the
    argument of the \\externalpage command.

    \target fn-command
    \section1 \\fn (function)

    The \\fn command is for documenting a function. The argument is
    the function's signature, including its template parameters (if
    any), return type, const-ness, and list of formal arguments with
    types. If the named function doesn't exist, QDoc emits a warning.

    Since QDoc version 6.0, the \\fn command can be used for documenting
    class members that are not explicitly declared in the header,
    but are implicitly generated by the compiler; default constructor
    and destructor, copy constructor and move-copy constructor,
    assignment operator, and move-assignment operator.

    When documenting an hidden friend, it is required to prepend the
    enclosing class name to the function name.
    For example, for:

    \code
    class Foo {
       ...
       friend bool operator==(const Foo&, const Foo&) { ... }
       ...
    }
    \endcode

    The command should be written as \c{"\fn Foo::operator==(const
    Foo&, const Foo&)"} and not as the free function \c{"\fn
    operator==(const Foo&, const Foo&)"}.

    Failure to do so will have QDoc complaining about being unable to
    resolve the function.

    \note The \\fn command is QDoc's default command: when no
    topic command can be found in a QDoc comment, QDoc tries to tie
    the documentation to the following code as if it is the
    documentation for a function. Hence, it is normally not necessary
    to include this command when documenting a function, if the
    function's QDoc comment is written immediately above the function
    implementation in the \c .cpp file. But it must be present when
    documenting an inline function in the \c .cpp file that is
    implemented in the \c .h file.

    \badcode *
    /\1!
        \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

        Returns \c true if this toolbar is dockable in the given
        \a area; otherwise returns \c false.
    \1/
    \endcode

    \note Running in debug mode (pass the \c {-debug} command line option
    or set the \c QDOC_DEBUG environment variable before invoking QDoc)
    can help troubleshoot \\fn commands that QDoc fails to parse. In
    debug mode, additional diagnostic information is available.

    See also \l {overload-command} {\\overload}.

    \target group-command
    \section1 \\group

    The \\group command creates a separate page that lists the classes,
    pages, or other entities belonging to a named group. The argument
    is the group name.

    A class is included in a group by using the \l {ingroup-command}
    {\\ingroup} command. Overview pages can also be related to a group
    using the same command, but the list of overview pages must be
    requested explicitly using the \l {generatelist-command}
    {\\generatelist} command (see example below).

    The \\group command is typically followed by a \l {title-command}
    {\\title} command and a short introduction to the group. The
    HTML page for the group is written to an \c {.html} file named
    <lower-case-group-name>.html.

    Each entity in the group is listed as a link (using page title
    or class name), followed by a decription from the \l {brief-command}
    {\\brief} command in the entity's documentation.

    \badcode *
    /\1!
        \group io
        \title Input/Output and Networking
    \1/
    \endcode

    QDoc generates a group page \c{io.html}.

    Note that overview pages related to the group must be listed
    explicitly using the \l {generatelist-command} {\\generatelist}
    command with the \c related argument.

    \badcode *
    /\1!
        \group architecture

        \title Architecture

        These documents describe aspects of Qt's architecture
        and design, including overviews of core Qt features and
        technologies.

        \generatelist{related}
    \1/
    \endcode

    See also \l {ingroup-command} {\\ingroup}, \l {annotatedlist-command}
    {\\annotatedlist}, \l {generatelist-command} {\\generatelist}, and
    \l {noautolist-command}{\\noautolist}.

    \target headerfile-command
    \section1 \\headerfile

    The \\headerfile command is for documenting the global functions,
    types and macros that are declared in a header file, but not in a
    namespace. The argument is the name of the header file. The HTML
    page is written to a \c {.html} file constructed from the header
    file argument.

    The documentation for a function, type, or macro that is declared
    in the header file being documented, is included in the header file
    page using the \l {relates-command} {\\relates} command.

    If the argument doesn't exist as a header file, the \\headerfile
    command creates a documentation page for the header file anyway.

    \badcode *
    /\1!
       \headerfile <QtAlgorithms>

       \title Generic Algorithms

       \brief The <QtAlgorithms> header file provides
        generic template-based algorithms.

       Qt provides a number of global template functions in \c
       <QtAlgorithms> that work on containers and perform
       well-know algorithms.
    \1/
    \endcode

    QDoc generates a header file page, \c{qtalgorithms.html}.

    See also \l {inheaderfile-command}{\\inheaderfile}.

    \target macro-command
    \section1 \\macro

    The \\macro command is for documenting a C++ macro. The argument
    is the macro in one of three styles: function-like macros like
    Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
    without parentheses like Q_OBJECT.

    The \\macro comment must contain a \l {relates-command}
    {\\relates} command that attaches the macro comment to a class,
    header file, or namespace. Otherwise, the documentation will be
    lost.

    \target module-command
    \section1 \\module

    The \\module creates a page that lists the classes belonging to
    the module specified by the command's argument. A class included
    in the module by including the \l {inmodule-command} {\\inmodule}
    command in the \\class comment.

    The \\module command is typically followed by a \l {title-command}
    {\\title} and a \l {brief-command} {\\brief} command. Each class
    is listed as a link to the class reference page followed by the
    text from the class's \l {brief-command} {\\brief} command. For
    example:

    \badcode *
    /\1!
        \module QtNetwork

        \title Qt Network Module

        \brief Contains classes for writing TCP/IP clients and servers.

        The network module provides classes to make network
        programming easier and portable. It offers both
        high-level classes such as QNetworkAccessManager that
        implements application-level protocols, and
        lower-level classes such as QTcpSocket, QTcpServer, and
        QUdpSocket.
    \1/
    \endcode

    The \l {noautolist-command} {\\noautolist} command can be used here
    to omit the automatically generated list of classes at the end.

    See also \l {inmodule-command} {\\inmodule}

    \target namespace-command
    \section1 \\namespace

    The \\namespace command is for documenting the contents of the C++
    namespace named as its argument. The reference page QDoc generates
    for a namespace is similar to the reference page it generates for a
    C++ class.

    \badcode *
    /\1!
        \namespace Qt

        \brief Contains miscellaneous identifiers used throughout the Qt library.
    \1/
    \endcode

    Note that in C++, a particular namespace can be used in more
    than one module, but when C++ elements from different modules
    are declared in the same namespace, the namespace itself must
    be documented in one module only. For example, namespace Qt in
    the example above contains types and functions from both QtCore
    and QtGui, but it is documented with the \\namespace command
    only in QtCore.

    \target page-command
    \section1 \\page

    The \\page command is for creating a stand-alone documentation
    page.

    The \\page command expects a single argument that represents the
    name of the file where QDoc should store the page.

    The page title is set using the \l {title-command} {\\title}
    command.

    \badcode *
    /\1!
       \page aboutqt.html

       \title About Qt

       Qt is a C++ toolkit for cross-platform GUI
       application development. Qt provides single-source
       portability across Microsoft Windows, macOS, Linux,
       and all major commercial Unix variants.

       Qt provides application developers with all the
       functionality needed to build applications with
       state-of-the-art graphical user interfaces. Qt is fully
       object-oriented, easily extensible, and allows true
       component programming.

       ...
    \1/
    \endcode

    QDoc renders this page in \c {aboutqt.html}.

    \target property-command
    \section1 \\property

    The \\property command is for documenting a Qt property. The
    argument is the full property name.

    A property is defined using the Q_PROPERTY() macro. The macro
    takes as arguments the property's name and its set, reset and get
    functions.

    \badcode
    Q_PROPERTY(QString state READ state WRITE setState)
    \endcode

    The set, reset and get functions don't need to be documented,
    documenting the property is sufficient. QDoc will generate a list
    of the access function that will appear in the property
    documentation which in turn will be located in the documentation
    of the class that defines the property.

    The \\property command comment typically includes a \l
    {brief-command} {\\brief} command. For properties the \l
    {brief-command} {\\brief} command's argument is a sentence
    fragment that will be included in a one line description of the
    property. The command follows the same rules for the
    description as the \l {variable-command} {\\variable} command.

    \badcode *
    /\1!
        \property QPushButton::flat
        \brief Whether the border is disabled.

        This property's default is false.
    \1/
    \endcode

    \target qmlattachedproperty-command
    \section1 \\qmlattachedproperty

    The \\qmlattachedproperty command is for documenting a QML
    property that will be attached to some QML type. See
    \l{Attached Properties and Attached Signal Handlers}
    {Attached Properties}. The argument is the rest of the line.
    It must start with the property type, followed by the QML
    type name where the property is declared, the \c{::}
    qualifier, and finally the property name.

    For example, to document a boolean QML attached property named
    \c isCurrentItem for the \c ListView type:

    \badcode *
    /\1!
        \qmlattachedproperty bool ListView::isCurrentItem

        This attached property is \c true if this delegate is the current
        item; otherwise false.

        It is attached to each instance of the delegate.

        This property may be used to adjust the appearance of the current
        item, for example:

        \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
    \1/
    \endcode

    QDoc includes this attached property on the QML reference page for the
    \l [QML] {ListView} type.

    \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedproperty
          accepts a QML module identifier as part of its argument.

    \target qmlattachedsignal-command
    \section1 \\qmlattachedsignal

    The \\qmlattachedsignal command is for documenting an attachable
    \l{Signal and Handler Event System}{signal}. The \\qmlattachedsignal
    command is used just like the \l{qmlsignal-command} {\\qmlsignal} command.

    The argument is the rest of the line. It should be the name of the
    QML type where the signal is declared, the \c{::}
    qualifier, and finally the signal name. For example, a QML
    attached signal named \c add() in the \c GridView
    element is documented like this:

    \badcode *
    /\1!
        \qmlattachedsignal GridView::add()
        This attached signal is emitted immediately after an item is added to the view.
    \1/
    \endcode

    QDoc includes this documentation on the QML reference page for the
    \l GridView element.

    \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedsignal accepts
          a QML module identifier as part of its argument.

    \target qmlvaluetype-command
    \section1 \\qmlvaluetype

    The \\qmlvaluetype command is for documenting a \l [QtQml]
    {QML Value Types}{value type} for QML. The command takes
    a type name as its only argument.

    \\qmlvaluetype is functionally identical to the
    \l {qmltype-command}{\\qmltype} command. The only difference
    is that the type will be titled (and grouped) as a
    \e {QML value type}.

    \target qmlclass-command
    \section1 \\qmlclass

    This command is deprecated. Use \l{qmltype-command} {\\qmltype}
    instead.

    \target qmlmethod-command
    \section1 \\qmlmethod

    The \\qmlmethod command is for documenting a QML method. The
    argument is the complete method signature, including return
    type and parameter names and types.

    \badcode *
    /\1!
        \qmlmethod void TextInput::select(int start, int end)

        Causes the text from \a start to \a end to be selected.

        If either start or end is out of range, the selection is not changed.

        After having called this, selectionStart will become the lesser, and
        selectionEnd the greater (regardless of the order passed to this method).

       \sa selectionStart, selectionEnd
    \1/
    \endcode

    QDoc includes this documentation on the element reference page for the
    \l{http://doc.qt.io/qt-5/qml-qtquick-textinput.html#select-method}
    {TextInput} element.

    \target qmltype-command
    \section1 \\qmltype

    The \\qmltype command is for documenting a QML type. The command
    has one argument, which is the name of the QML type.

    If the QML type is instantiated by a C++ class, that class must be
    specified using the \l{instantiates-command} {\\instantiates}
    context command.

    The \l {inqmlmodule-command}{\\inqmlmodule} command documents the
    QML module the type belongs to. The argument passed to this command
    must match with a documented \l {qmlmodule-command}{\\qmlmodule}
    page.

    \badcode *
    /\1!
        \qmltype Transform
        \instantiates QGraphicsTransform
        \inqmlmodule QtQuick

        \brief Provides a way to build advanced transformations on Items.

        The Transform element is a base type which cannot be
        instantiated directly.
    \1/
    \endcode

    Here, the \e{\\qmltype} comment includes \l{instantiates-command}
    {\\instantiates} to specify that a Transform is instantiated by
    the C++ class QGraphicsTransform. A \\qmltype comment should
    always include a \l {since-command} {\\since} command, because all
    QML types are new. It should also include a \l{brief-command}
    {\\brief} description. If a QML type is a member of a QML type group,
    the \\qmltype comment should include one or more \l{ingroup-command}
    {\\ingroup} commands.

    \target qmlproperty-command
    \section1 \\qmlproperty

    The \\qmlproperty command is for documenting a QML property. The
    argument is the rest of the line. The argument text should be the
    property type, followed by the QML type name, the \c{::}
    qualifier, and finally the property name. If we have a QML
    property named \c x in QML type \c Translate, and the property
    has type \c {real}, the \\qmlproperty for it would look like this:

    \badcode *
    /\1!
        \qmlproperty real Translate::x

        The translation along the X axis.
    \1/
    \endcode

    QDoc includes this QML property on the QML reference page for the
    \l [QML] {Translate} type.

    If the QML property is of enumeration type, or it holds a bit-wise
    combination of flags, the \l{value-command}{\\value} command can
    be used to document the acceptable values.

    QDoc accepts also a fully qualified property name, including the
    QML module identifier:

    \badcode
    \qmlproperty bool QtQuick.Controls::Button::highlighted
    \endcode

    If specified, the module identifier (above, \c {QtQuick.Controls})
    must match with value passed to \l {inqmlmodule-command}{\\inqmlmodule}
    command in the associated \\qmltype documentation. If the name of
    the QML type the property belongs to is unique across all types in
    the documentation project, the module identifier can be omitted.

    \target qmlsignal-command
    \section1 \\qmlsignal

    The \\qmlsignal command is for documenting a QML signal.
    The argument is the rest of the line. The arguments should be: the QML type
    where the signal is declared, the \c{::} qualifier, and finally the signal
    name. If we have a QML signal named \c clicked(), the documentation for it
    would look like this:

    \badcode *
    /\1!
        \qmlsignal MouseArea::clicked(MouseEvent mouse)

        This signal is emitted when there is a click. A click is defined as a
        press followed by a release, both inside the MouseArea.
    \1/
    \endcode

    QDoc includes this documentation on the QML reference page for the
    \l [QML] {MouseArea} type.

    \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlsignal
          accepts a QML module identifier as part of its argument.

    \target qmlmodule-command
    \section1 \\qmlmodule

    Use the \c{\qmlmodule} command to create a \c QML module page. A QML
    module page is a collection of QML types or any related material. The
    command takes an optional \c <VERSION> number argument, and is similar
    to the \l{group-command}.

    A QML type is associated with a module by adding the
    \l{inqmlmodule-command}{\\inqmlmodule} command to the comment-block that
    documents the type. You can link to any member of a QML module using the
    module name and two colons (\c{::}) prefix.

    \badcode *
    /\1!
        A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
    \1/
    \endcode

    QDoc generates a page for the module that lists all the members of the
    module.

    \badcode *
    /\1!
        \qmlmodule ClickableComponents

        This is a list of the Clickable Components set. A Clickable component
        responds to a \c clicked() event.
    \1/
    \endcode

    \target inqmlmodule-command
    \section1 \\inqmlmodule

    A QML type is marked as being available under a specific QML module
    import by inserting the \\inqmlmodule command in a
    \l {qmltype-command}{\\qmltype} topic. The command takes the module
    (import) name, without a version number, as the only argument.

    The QML module name must match with a QML module documented with
    the (\l{qmlmodule-command}{\\qmlmodule} command).

    \badcode *
    /\1!
        \qmltype ClickableButton
        \inqmlmodule ClickableComponents

        A clickable button that responds to the \c click() event.
    \1/
    \endcode

    QDoc outputs a row \e {Import statement: import <qmlmodule>}
    in a table at the top of the QML type reference page.

    When linking to QML types, the QML module identifier may appear in
    the link target. For example:

    \badcode
    \l {ClickableComponents::}{ClickableButton}
    \endcode

    Links to the type reference page, with \e ClickableButton as the
    link text.

    \target instantiates-command
    \section1 \\instantiates

    The \\instantiates command is used in the \l{qmltype-command} {QML
    type} comment of an elemental QML type to specify the name of the
    C++ class that instantiates the QML type.

    If the QML type is not instantiated by a C++ class, this command
    is not used.

    \badcode *
    /\1!
        \qmltype Transform
        \instantiates QGraphicsTransform
        \inqmlmodule QtQuick

        \brief Provides a way to build advanced transformations on Items.

        The Transform element is a base type which cannot be
        instantiated directly.
    \1/
    \endcode

    Here, the \e{\\qmltype} comment includes \l{instantiates-command}
    {\\instantiates} to specify that a Transform is instantiated by
    the C++ class QGraphicsTransform.

    \target typealias-command
    \section1 \\typealias

    The \\typealias command is similar to \l {typedef-command}{\\typedef},
    but specific to documenting a C++ type alias:

    \code
    class Foo
    {
    public:
        using ptr = void*;
    // ...
    }
    \endcode

    This can be documented as

    \badcode *
    /\1!
        \typealias Foo::ptr
    \1/
    \endcode

    The \\typealias command was introduced in QDoc 5.15.

    See also \l {typedef-command}{\\typedef}.

    \target typedef-command
    \section1 \\typedef

    The \\typedef command is for documenting a C++ typedef. The
    argument is the name of the typedef. The documentation for
    the typedef will be included in the reference documentation
    for the class, namespace, or header file in which the typedef
    is declared. To relate the \\typedef to a class, namespace, or
    header file, the \\typedef comment must contain a
     \l {relates-command} {\\relates} command.

    \badcode *
    /\1!
        \typedef QObjectList
        \relates QObject

        Synonym for QList<QObject>.
    \1/
    \endcode

    Other typedefs are located on the reference page for the class
    that defines them.

    \badcode *
    /\1!
        \typedef QList::Iterator

        Qt-style synonym for QList::iterator.
    \1/
    \endcode

    See also \l {typealias-command}{\\typealias}.

    \target variable-command
    \section1 \\variable

    The \\variable command is for documenting a class member variable
    or a constant. The argument is the variable or constant name. The
    \\variable command comment includes a \l {brief-command} {\\brief}
    command. QDoc generates the documentation based on the text from
    \\brief command.

    The documentation will be located in the in the associated class,
    header file, or namespace documentation.

    In case of a member variable:

    \badcode *
    /\1!
        \variable QStyleOption::palette
        \brief The palette that should be used when painting
               the control
    \1/
    \endcode

    You can also document constants with the \\variable command. For
    example, suppose you have the \c Type and \c UserType constants in
    the QTreeWidgetItem class:

    \code
    enum { Type = 0, UserType = 1000 };
    \endcode

    For these, the \\variable command can be used this way:

    \badcode *
    /\1!
        \variable QTreeWidgetItem::Type

        The default type for tree widget items.

        \sa UserType, type()
    \1/
    \endcode

    \badcode *
    /\1!
        \variable QTreeWidgetItem::UserType

        The minimum value for custom types. Values below
        UserType are reserved by Qt.

        \sa Type, type()
    \1/
    \endcode

*/