qdoc-manual-topiccmds.qdoc

Go to the documentation of this file.

// 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 documented 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.
 
    The command accepts \c auto as the type of a function, even though
    the full type can be deduced by QDoc. In certain situations, it may
    be preferable to use \e auto instead of the actual type of a
    function. Using \c auto as the return type in the
    \\fn-command lets the author to do this explicitly, also for types
    that are defined without the \e auto keyword.
 
    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 qmlenum-command
    \section1 \\qmlenum
 
    The \\qmlenum command is for documenting a QML enumeration. The command
    takes a single argument: the full name of the enumeration type, including
    the parent QML type and, optionally, the QML module.
 
    The enumerators and their descriptions are documented using
    \qdoccmd {value} commands.
 
    For example,
 
    \badcode *
    /\1!
        \qmlenum My.Module::Color::Channel
        \brief Specifies a color channel in the RGB colorspace.
 
        \value R
               Red color channel
 
        \value G
               Green color channel
 
        \value B
               Blue color channel
    \1/
    \endcode
 
    This generates documentation for an enumeration \e Channel, with three
    enumerators: \e {Color.R}, \e {Color.G}, and \e {Color.B}.
 
    Alternatively, it's possible to replicate the enumerators' documentation
    from an existing C++ \qdoccmd {enum} topic, by using the
    \qdoccmd {qmlenumeratorsfrom} command.
 
    This command was introduced with Qt 6.10.
 
    See also \qdoccmd {qmlenumeratorsfrom}.
 
    \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 has an equivalent C++ class, you can specify that class
    with the \qdoccmd nativetype 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
        \nativetype 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 \qdoccmd nativetype
    to specify that a Transform is the QML counterpart to 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.
 
    \note QDoc automatically detects QML singleton types when the corresponding
    C++ class uses the \c{QML_SINGLETON} macro. For such types, using
    \qdoccmd {qmltype} is sufficient, as the singleton nature will be detected
    and documented automatically.
 
    \target qmlsingletontype-command
    \section1 \\qmlsingletontype
 
    The \\qmlsingletontype command is for explicitly documenting a QML singleton type.
    This command is functionally identical to \l{qmltype-command}{\\qmltype}, but it
    explicitly marks the type as a singleton regardless of the C++ implementation.
 
    A QML singleton type ensures only one instance exists in the QML engine.
    The singleton designation is displayed in the generated documentation with
    a "(Singleton)" indicator in the title and an explanatory note.
 
    \badcode *
    /\1!
        \qmlsingletontype Settings
        \inqmlmodule MyApp
 
        \brief Provides application-wide settings as a singleton.
 
        The Settings type is a singleton that maintains application
        configuration. Access it directly without instantiation.
    \1/
    \endcode
 
    For C++ classes that use the \c{QML_SINGLETON} macro, prefer using
    \qdoccmd {qmltype} instead, as QDoc will automatically detect the singleton
    nature from the C++ code.
 
    \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.
 
    The \l{default-command}{\\default} command is used to document the
    default value of a property:
 
    \badcode
    \qmlproperty real AxisHelper::gridOpacity
    \default 0.5
    \endcode
 
    If the QML property exposes a C++ enum, the QML property is defined
    with type \c{enumeration}:
 
    \badcode
    \qmlproperty enumeration ParticleShape3D::ShapeType
    \endcode
 
    Properties with enumeration type and those that hold a bit-wise
    combination of flags can use the \l{value-command}{\\value} command
    to document the acceptable values.
 
    \badcode
    \qmlproperty enumeration Buffer::textureFilterOperation
    Specifies the texture filtering mode...
    \value Buffer.Nearest Use nearest-neighbor filtering.
    \endcode
 
    QDoc also accepts 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 the value passed to the \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 deprecated since Qt 6.8.
    Use \qdoccmd nativetype instead.
 
 
    \target nativetype-command
    \section1 \\nativetype
 
    The \\nativetype-command must be used in conjunction with the
    \qdoccmd qmltype topic command. The command takes a C++ class as its
    argument. If QDoc cannot find the C++ class, it issues a warning. This
    command was introduced with Qt 6.8.
 
    Use the \\nativetype-command to specify what the type is called in C++.
    This ensures that the requisites block generated in the documentation for
    the QML type contains an "In C++" entry. The C++ class will have a
    corresponding "In QML" entry.
 
    Any one QML type can only have one native type. QDoc issues a warning if
    redefinition occurs. However, multiple QML types can have the same C++
    class as their native type. The C++ class documentation will contain a list
    of all corresponding types in QML.
 
    \badcode *
    /\1!
        \qmltype Transform
        \nativetype 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} topic includes \e{\\nativetype} to specify that a
    Transform is called QGraphicsTransform in C++.
 
 
    \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
 
*/