qdoc-manual-markupcmds.qdoc

Go to the documentation of this file.

// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page 03-qdoc-commands-markup.html
    \previouspage Naming Things
    \nextpage Macros
 
    \title Markup Commands
 
    The markup commands indicate the generated documentation's visual
    appearance and logical structure.
 
    \list
    \li \l {a-command} {\\a}
    \li \l {annotatedlist-command} {\\annotatedlist}
    \li \l {b-command} {\\b}
    \li \l {badcode-command} {\\badcode}
    \li \l {b-command} {\\bold} (deprecated, use \\b)
    \li \l {br-command} {\\br}
    \li \l {brief-command} {\\brief}
    \li \l {c-command} {\\c}
    \li \l {caption-command} {\\caption}
    \li \l {code-command} {\\code}
    \li \l {codeline-command} {\\codeline}
    \li \l {details-command} {\\details}
    \li \l {div-command} {\\div}
    \li \l {dots-command} {\\dots}
    \li \l {e-command} {\\e}
    \li \l {else-command} {\\else}
    \li \l {endif-command} {\\endif}
    \li \l {generatelist-command} {\\generatelist}
    \li \l {header-command} {\\header}
    \li \l {e-command} {\\i} (deprecated, use \\e)
    \li \l {if-command} {\\if}
    \li \l {image-command} {\\image}
    \li \l {include-command} {\\include}
    \li \l {inlineimage-command} {\\inlineimage}
    \li \l {keyword-command} {\\keyword}
    \li \l {l-command} {\\l}
    \li \l {legalese-command} {\\legalese}
    \li \l {li-command} {\\li}
    \li \l {list-command} {\\list}
    \li \l {meta-command} {\\meta}
    \li \l {noautolist-command} {\\noautolist}
    \li \l {li-command} {\\o} (deprecated, use \\li)
    \li \l {note-command} {\\note}
    \li \l {notranslate-command} {\\notranslate}
    \li \l {omit-command} {\\omit}
    \li \l {printline-command} {\\printline}
    \li \l {printto-command} {\\printto}
    \li \l {printuntil-command} {\\printuntil}
    \li \l {qml-command}{\\qml}
    \li \l {quotation-command} {\\quotation}
    \li \l {quotefile-command} {\\quotefile}
    \li \l {quotefromfile-command} {\\quotefromfile}
    \li \l {raw-command} {\\raw}
    \li \l {row-command} {\\row}
    \li \l {sa-command} {\\sa}
    \li \l {sectionOne-command} {\\section1}
    \li \l {sectionTwo-command} {\\section2}
    \li \l {sectionThree-command} {\\section3}
    \li \l {sectionFour-command} {\\section4}
    \li \l {sincelist-command} {\\sincelist}
    \li \l {skipline-command} {\\skipline}
    \li \l {skipto-command} {\\skipto}
    \li \l {skipuntil-command} {\\skipuntil}
    \li \l {snippet-command} {\\snippet}
    \li \l {span-command} {\\span}
    \li \l {sub-command} {\\sub}
    \li \l {sup-command} {\\sup}
    \li \l {table-command} {\\table}
    \li \l {target-command} {\\target}
    \li \qdoccmd tm
    \li \l {tt-command} {\\tt}
    \li \l {uicontrol-command} {\\uicontrol}
    \li \l {underline-command} {\\underline}
    \li \l {raw-command} {\\unicode}
    \li \l {warning-command} {\\warning}
    \li \l {backslash-sequence} {\\\\}
    \li \l {endash-sequence} {\--}
    \li \l {emdash-sequence} {-\--}
    \endlist
*/
 
 
/*!
    \page 04-qdoc-commands-textmarkup.html
    \previouspage Markup Commands
    \nextpage Document Structure
 
    \title Text Markup
 
    The text formatting commands indicate how text is to be rendered.
 
    \target a-command
    \section1 \\a (parameter marker)
 
    The \\a command tells QDoc the next word is a formal parameter name.
 
    A warning is emitted when a formal parameter is not documented or
    is misspelled, so when you document a function you should mention
    each formal parameter by name in the function description,
    preceded by the \\a command. The parameter name is then rendered
    in italics.
 
    The formal parameter name may be enclosed between curly brackets,
    but that isn't required.
 
    \target c-command
    \section1 \\c (code font)
 
    The \\c command is used for rendering variable names, user-defined
    class names, and C++ keywords (for example, \c int and \c for) in the code
    font.
 
    The command renders its argument using a monospace font. If the text to be
    rendered in the code font contains spaces, enclose the entire text in curly
    brackets:
 
    \code
      \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) : QWidget(parent)}
    \endcode
 
    The \\c command accepts the special character \c \ within its
    argument, which renders it as a normal character. So if you want
    to use nested commands, you must use the \l {tt-command} {teletype
    (\\tt)} command instead.
 
    See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
 
    \target details-command
    \section1 \\details (collapsible)
 
    The \\details and \\enddetails commands generates a collapsible <details>
    element with a <summary> to control the hidden/visible state.
 
    When generating HTML output, use the \\details and \\enddetails commands to
    generate a collapsible \c{<details>} HTML element. The command takes an
    optional summary string enclosed in curly braces. This optional argument
    specifies a visible heading for the details.
 
    For example, with the following input:
    \badcode *
        /\1!
            \details {QDoc details}
              \note You're looking at detailed information.
            \enddetails
        \1/
    \endcode
 
    If QDoc is generating HTML, it will translate these commands to:
 
    \badcode
    <summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div>
    \endcode
 
    QDoc renders this as:
 
    \details {QDoc details}
       \note You're looking at detailed information.
    \enddetails
 
    For any other output format, QDoc generates the contents as a normal paragraph,
    ignoring the summary string. This command was introduced to QDoc in Qt6.6.
 
    \target div-command
    \section1 \\div
 
    The \\div and \\enddiv commands delimit a large or small block of
    text (which may include other QDoc commands) to which special
    formatting attributes should be applied.
 
    An argument must be provided in curly braces, as in the QDoc
    comment shown below. The argument is not interpreted but is used
    as attribute(s) of the tag that is output by QDoc.
 
    For example, we might want to render an inline image so that it
    floats to the right of the current block of text:
 
    \badcode *
    /\1!
        \div {class="float-right"}
            \inlineimage qml-column.png
        \enddiv
    \1/
    \endcode
 
    If QDoc is generating HTML, it will translate these commands to:
 
    \code
      <div class="float-right"><p><img src="images/qml-column.png" /></p></div>
    \endcode
 
    For HTML, the attribute value \e {float-right} then will refer to
    a clause in the style.css file, which in this case could be:
 
    \code
       div.float-right
       {
          float: right; margin-left: 2em
       }
    \endcode
 
    \note Note that the \b {\\div} command can be nested.
 
    Below you can find an example taken from the index.qdoc file used to
    generate index.html for Qt 4.7:
 
    \code
        \div {class="indexbox guide"}
            \div {class="heading"}
                Qt Developer Guide
        \enddiv
            \div {class="indexboxcont indexboxbar"}
                \div {class="section indexIcon"} \emptyspan
                \enddiv
                \div {class="section"}
                    Qt is a cross-platform application and UI
                    framework. Using Qt, you can write web-enabled
                    applications once and deploy them across desktop,
                    mobile and embedded operating systems without
                    rewriting the source code.
                \enddiv
                \div {class="section sectionlist"}
                    \list
                       \li \l{Getting Started}
                       \li \l{Installation} {Installation}
                       \li \l{how-to-learn-qt.html} {How to learn Qt}
                       \li \l{tutorials.html} {Tutorials}
                       \li \l{Qt Examples} {Examples}
                       \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
                    \endlist
                \enddiv
            \enddiv
        \enddiv
    \endcode
 
    When all the class attribute values are defined as they are in the
    style.css file that is used for rendering the Qt documentation,
    the above example is rendered as:
 
          \div {class="indexbox guide"}
            \div {class="heading"}
              Qt Developer Guide
        \enddiv
            \div {class="indexboxcont indexboxbar"}
              \div {class="section indexIcon"} \emptyspan
              \enddiv
              \div {class="section"}
                Qt is a cross-platform application and UI
                framework. Using Qt, you can write web-enabled
                applications once and deploy them across desktop,
                mobile and embedded operating systems without
                rewriting the source code.
              \enddiv
              \div {class="section sectionlist"}
                \list
                  \li Getting Started
                  \li Installation
                  \li How to learn Qt
                  \li Tutorials
                  \li Examples
                  \li What's new in Qt 4.7
                \endlist
             \enddiv
            \enddiv
          \enddiv
 
    See also \l {span-command} {\\span}.
 
    \target span-command
    \section1 \\span
 
    The \\span command applies special formatting to a small block of text.
 
    Two arguments must be provided, each argument in curly braces, as
    shown in the QDoc comment below. The first argument is not
    interpreted, but specifies the formatting attribute(s) of the tag
    output by QDoc. The second argument is the text to be rendered with
    the special formatting attributes.
 
    For example, we might want to render the first word of each
    element in a numeric list in blue.
 
    \badcode *
        /\1!
            Global variables with complex types:
        \list 1
                \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
                \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
                \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
                \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
            \endlist
        \1/
    \endcode
 
    Class \e {variableName} refers to a clause in your style.css.
 
    \code
        .variableName
        {
            font-family: courier;
        color: blue
        }
    \endcode
 
    Using the \e {variableName} clause shown above, the example is rendered as:
 
    Global variables with complex types:
    \list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
 
    \note The \b span command does not cause a new paragraph to be
    started.
 
    See also \l {div-command} {\\div}.
 
    \target tm-command
    \section1 \\tm (trademark)
 
    The \\tm command indicates that its argument is a trademark. QDoc appends
    a trademark symbol `™` to the first occurrence of the argument when
    generating a page.
 
    In the project's configuration, the \c navigation.trademarkspage variable
    is used for defining a title of a page that contains trademark-related
    documentation.
 
    \badcode
    navigation.trademarkspage = Trademarks
    \endcode
 
    If set, each occurrence of the trademark symbol also links to the
    trademarks page.
 
    \note In section titles, the \\tm command is ignored and its argument
          rendered as-is.
 
    See also \l {sectionOne-command}{\\section1} and \qdocvar {navigation}.
 
    \target tt-command
    \section1 \\tt (teletype font)
 
    The \\tt command renders its argument in a monospace font. This
    command behaves just like the \l {c-command} {\\c} command, except
    that \\tt allows you to nest QDoc commands within the argument
    (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l
    {underline-command} {\\underline}).
 
    \badcode *
       /\1!
           After having populated the main container with
           child widgets, \c setupUi() scans the main container's list of
           slots for names with the form
           \tt{on_\e{objectName}_\e{signalName}().}
       \1/
    \endcode
 
    If the text to be rendered in the code font contains spaces, enclose the
    entire text in curly brackets.
 
    \code
      \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
    \endcode
 
    See also \l {c-command} {\\c}.
 
    \target b-command
    \section1 \\b
 
    The \\b command renders its argument in bold font. This command used
    to be called \\bold.
 
    \badcode *
    /\1!
        This is regular text; \b {this text is
        rendered using the \\b command}.
    \1/
    \endcode
 
    \target br-command
    \section1 \\br
 
    The \\br command forces a line break.
 
    \target e-command
    \section1 \\e (emphasis, italics)
 
    The \\e command renders its argument in a special font, normally italics. This
    command used to be called \\i, which is now deprecated.
 
    If the argument contains spaces or other punctuation, enclose the
    argument in curly brackets.
 
    \badcode *
    /\1!
        Here, we render \e {a few words} in italics.
    \1/
    \endcode
 
    If you want to use other QDoc commands within an argument that
    contains spaces, you always need to enclose the argument in
    braces. But QDoc is smart enough to count parentheses, so you
    don't need braces in cases like this:
 
    \badcode *
    /\1!
        An argument can sometimes contain whitespaces,
        for example: \e QPushButton(tr("A Brand New Button"))
    \1/
    \endcode
 
    Finally, trailing punctuation is not included in an argument,
    nor is "'s".
 
    \target sub-command
    \section1 \\sub
 
    The \\sub command renders its argument lower than the baseline of
    the regular text, using a smaller font.
 
    \badcode *
    /\1!
        Definition (Range): Consider the sequence
        {x\sub n}\sub {n > 1} . The set
 
        {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
 
        is called the range of the sequence.
    \1/
    \endcode
 
    If the argument contains spaces or other punctuation, enclose the
    argument in curly brackets.
 
    \target sup-command
    \section1 \\sup
 
    The \\sup command renders its argument higher than
    the baseline of the regular text, using a smaller font.
 
    \badcode *
    /\1!
        The series
 
        1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
 
        is called the \i {geometric series}.
    \1/
    \endcode
 
    If the argument contains spaces or other punctuation, enclose the
    argument in curly brackets.
 
    \target uicontrol-command
    \section1 \\uicontrol
 
    The \\uicontrol command is used to mark content as being used for UI
    control elements. When using HTML, the output is rendered in bold.
 
    See also \l {b-command}{\\b}.
 
    \target underline-command
    \section1 \\underline
 
    The \\underline command renders its argument underlined.
 
    \badcode *
    /\1!
        The \underline {F}ile menu gives the users the possibility
        to edit an existing file, or save a new or modified
        file, and exit the application.
    \1/
    \endcode
 
    If the argument contains spaces or other punctuation, enclose the
    argument in curly brackets.
 
    \target backslash-sequence
    \section1 \\\\ (double backslash)
 
    The sequence \\\\ expands to a single backslash.
 
    QDoc commands always start with a single backslash. To display a
    single backslash in the text, you must type two backslashes. If
    you want to display two backslashes, you must type four.
 
    \badcode *
    /\1!
        The \\\\ command is useful if you want a
        backslash to appear verbatim, for example,
        writing C:\\windows\\home\\.
    \1/
    \endcode
 
    However, if you want your text to appear in a monospace font as
    well, you can use the \l {c-command} {\\c} command instead, which
    accepts and renders the backslash as any other character. For
    example:
 
    \badcode *
    /\1!
        The \\c command is useful if you want a
        backslash to appear verbatim, and the word
        that contains it written in a monospace font,
        like this: \c {C:\windows\home\}.
    \1/
    \endcode
 
    \target endash-sequence
    \section1 \-- (en dash)
    QDoc renders double hyphens as an en dash. QDoc markup commands
    designed to make their input appear verbatim---such as the \\c
    command---won't replace the double hyphens with an en dash character.
    For example:
 
    \badcode *
        /\1!
            The \\c command -- useful if you want text in a monospace font --
            is well documented.
        \1/
    \endcode
 
    However, other commands may require that the hyphens are escaped to ensure
    QDoc renders the output as expected. For example;
 
    \badcode *
    /\1!
        This \l {endash-sequence}{link to the -- (endash) sequence}
        isn't escaped and QDoc therefore renders an endash in the link
        text. However, the escaped
        \l {endash-sequence}{link to the \-- (endash) sequence}
        renders both hyphens as intended.
    \1/
    \endcode
 
    See also \l {emdash-sequence}{\-\-- (em dash)}.
 
    \target emdash-sequence
    \section1 -\-- (em dash)
 
    QDoc renders triple hyphens as an en dash. QDoc markup commands
    designed to make their input appear verbatim---such as the \\c
    command---won't replace the triple hyphens with an en dash character.
    For example:
 
    \badcode *
    /\1!
        The \\c command---useful when you want text to be rendered
        verbatim---is well documented.
    \1/
    \endcode
 
    However, other commands may require that the hyphens are escaped to ensure
    QDoc renders the output as expected. For example;
 
    \badcode *
    /\1!
        This \l {emdash-sequence}{link to the --- (emdash) sequence}
        isn't escaped and QDoc therefore renders an emdash in the link
        text. However, the escaped
        \l {emdash-sequence}{link to the -\-- (emdash) sequence}
        renders both hyphens as intended.
    \1/
    \endcode
 
    \note The escaped control sequence in this example is for the en dash.
          This avoids a hyphen followed by an en dash in the output.
 
    See also \l {endash-sequence}{\-- (en dash)}.
*/
 
 
/*!
    \page 05-qdoc-commands-documentstructure.html
    \previouspage Text Markup
    \nextpage Including Code Inline
 
    \title Document Structure
 
    The document structuring commands are for dividing your document
    into sections. QDoc supports four levels of section: \c \section1,
    \c \section2, \c \section3, and \c \section4. The section commands
    correspond to the traditional section, subsection, etc used in
    outlining.
 
    \section1 Section commands
 
    In general a document structuring command considers everything
    that follows it until the first line break as its argument. The
    argument is rendered as the unit's title. If the title needs to be
    spanned over several lines, make sure that each line (except the
    last one) is ended with a backslash.
 
    In total, there are four levels for sections in QDoc: \c \section1,
    \c \section2, \c \section3 and \c \section4. These correspond to the
    traditional section, subsection, subsubsection and subsubsubsection.
 
    There is a strict ordering of the section units:
 
    \code
    section1
          |
          section2
                 |
                 section3
                        |
                        section4
    \endcode
 
    When sections are used, the first section command should be \c section1.
 
    \badcode *
    /\1!
        \section1 Basic Qt
 
        This is the first section.
 
 
            \section2 Getting Started
 
            This is the first subsection.
 
 
                \section3 Hello Qt
 
                This is the first subsubsection.
 
 
                \section3 Making Connections
 
                This is the second subsubsection.
 
 
                \section3 Using the Reference Documentation
 
                This is the third subsubsection.
 
 
            \section2 Creating Dialogs
 
            This is the second subsection.
 
 
                \section3 Subclassing QDialog
 
                This is the first subsubsection.
 
                ...
 
 
        \section1 Intermediate Qt
 
        This is the second section.
 
 
            \section2 Layout Management
 
            This is the second section's first subsection.
 
 
                \section3 Basic Layouts
 
                This is the first subsubsection.
 
            ...
    \1/
    \endcode
 
    Each section is a logical unit in the document. The section
    heading appears in the automatically generated table of contents
    that normally appears in the upper right-hand corner of the page.
 
    \target sectionOne-command
    \section1 \\section1
 
    The \\section1 command starts a new section.
 
    See \l{section-commands} {Section commands} for an explanation of the various
    section units, command argument, and rendering.
 
    \target sectionTwo-command
    \section1 \\section2
 
    The \\section2 command starts a new section.
 
    See \l{section-commands} {Section commands} for an explanation of the various
    section units, command argument, and rendering.
 
    \target sectionThree-command
    \section1 \\section3
 
    The \\section3 command starts a new section.
 
    See \l{section-commands} {Section commands} for an explanation of the various
    section units, command argument, and rendering.
 
    \target sectionFour-command
    \section1 \\section4
 
    The \\section4 command starts a new section.
 
    See \l{section-commands} {Section commands} for an explanation of the various
    section units, command argument, and rendering.
 
*/
 
 
/*!
    \page 06-qdoc-commands-includecodeinline.html
    \previouspage Document Structure
    \nextpage Including External Code
 
    \title Including Code Inline
 
    The following commands are used to render source code without
    formatting. The source code begins on a new line, rendered in the
    code.
 
    \note Although most of these commands are for rendering C++
    code, the
    \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
    {\\snippet} and
    \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
    {\\codeline} commands are preferred over the others. These
    commands allow equivalent code snippets for other Qt language
    bindings to be substituted for the C++ snippets in the
    documentation.
 
    \target code-command
    \section1 \\code
 
    The \\code and \\endcode commands enclose a snippet of source code.
 
    \note The \l {c-command} {\\c} command can be used for short code
    fragments within a sentence. The \\code command is for longer code
    snippets. It renders the code verbatim in a separate paragraph in
    a html <pre> element, and parses the enclosed snippet, creating links
    to any known types in the code.
 
    For documenting command-line instructions, shell scripts, or any
    content that is not in a Qt language recognized by QDoc, use
    \l {badcode-command}{\\badcode} instead.
 
    When processing the \\code command, QDoc removes all indentation
    that is common for the verbatim code blocks within a \c{/}\c{*!}
    ... \c{*}\c{/} comment before it adds the standard indentation.
 
    \note This doesn't apply to externally quoted code using the \l
    {quotefromfile-command} {\\quotefromfile} or \l
    {quotefile-command} {\\quotefile} command.
 
       \code \\endcode *
       /*!
           \code
               #include <QApplication>
               #include <QPushButton>
 
               int main(int argc, char *argv[])
               {
                   ...
               }
           \1
       \2/
       \endcode
 
    Other QDoc commands are disabled within \\code... \\endcode, and
    the special character '\\' is accepted and rendered like the rest
    of the code, unless it is followed by a digit and parameters were
    passed to \\code.
 
    \section2 Highlighting and autolinking
 
    The \\code commands attempts to parse its contents as code of a
    specific language, as defined in the \l {language-variable}{language}
    configuration variable. This provides highlighting and automatic
    linking to types detected in the code.
 
    As an exception since QDoc version 6.4, when the \\code command
    is used within a QML-specific \l {Topic Commands}{topic}, QDoc
    first attempts to recognize the code as QML; for other topics,
    the language configuration variable takes precedence. To
    explicitly mark the code snippet as QML, use the \l {qml-command}
    {\\qml} command instead.
 
    \section2 Code snippet parameters
 
    Since QDoc version 5.12, \\code command accepts also optional
    parameters. Parameters are useful for injecting simple
    strings into the code snippet. To inject a string to a specific
    location in the snippet, add a backslash followed by a digit (1..8).
    The digits correspond with the order of the argument list, where
    arguments are separated by spaces.
 
    For example:
 
    \badcode 1 2 * endcode
    /\3!
        \code * hello
        /\\1 \\2 \\1/
        \\4
    \3/
    \endcode
 
    For the above snippet, QDoc renders the word \e hello enclosed in
    a C-style comment.
 
    \section2 Including code from external files
 
    To include code snippets from an external file, use the
    \l{snippet-command}{\\snippet} and \l{codeline-command}
    {\\codeline} commands.
 
    See also \l {c-command}{\\c}, \l {qml-command}{\\qml},
    \l {badcode-command}{\\badcode}, \l {quotefromfile-command}
    {\\quotefromfile}, and \l {language-variable}{language}.
 
    \target badcode-command
    \section1 \\badcode
 
    Similar to \l {code-command}{\\code}, \\badcode and \\endcode commands
    enclose content that is rendered verbatim in a separate paragraph, but no
    parsing or automatic link creation is performed. Instead, the content is
    treated as plain text.
 
    Substitute \\code with this command when documenting command-line
    instructions, shell scripts or any other content that is not in a Qt
    language, but should still be styled similarly to a \\code paragraph.
 
    Like \\code, \\badcode accepts also optional parameters.
 
    \target qml-command
    \section1 \\qml
 
    The \\qml and \\endqml commands enclose a snippet of QML source
    code. Use these for proper syntax highlighting of QML code snippets.
    The enclosed snippet must be complete as if it was a valid .qml file.
    If the snippet is incomplete, QDoc will issue a warning and ignore the
    snippet.
 
    \badcode *
    /\1!
        \qml
            import QtQuick 2.0
 
            Row {
                Rectangle {
                    width: 100; height: 100
                    color: "blue"
                    transform: Translate { y: 20 }
                }
                Rectangle {
                    width: 100; height: 100
                    color: "red"
                    transform: Translate { y: -20 }
                }
            }
        \endqml
    \1/
    \endcode
 
    Like the \l{code-command}{\\code} command, \\qml accepts optional
    parameters.
*/
 
 
/*!
    \page 07-0-qdoc-commands-includingexternalcode.html
    \previouspage Including Code Inline
    \nextpage Creating Links
 
    \title Including External Code
 
    The following commands enable you to include code snippets from
    external files. You can make QDoc include the complete contents of
    a file, or you can quote specific parts of the file and skip
    others. The typical use of the latter is to quote a file chunk by
    chunk.
 
    \note Although all these commands can be used for rendering C++
    code, the
    \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
    {\\snippet} and
    \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
    {\\codeline} commands are preferred over the others. These
    commands allow equivalent code snippets for other Qt language
    bindings to be substituted for the C++ snippets in the
    documentation.
 
    \target quotefile-command
    \section1 \\quotefile
 
    The \\quotefile command expands to the complete contents of the
    file given as argument.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the file name with a line break.
 
    The file's contents is rendered in a separate paragraph, using a
    monospace font and the standard indentation. The code is shown
    verbatim.
 
    \badcode *
    /\1!
       This is a simple "Hello world" example:
 
       \quotefile examples/main.cpp
 
       It contains only the bare minimum you need
       to get a Qt application up and running.
    \1/
    \endcode
 
    See also \l {quotefromfile-command} {\\quotefromfile} and
    \l {code-command} {\\code}.
 
 
    \target quotefromfile-command
    \section1 \\quotefromfile
 
    The \\quotefromfile command opens the file given as argument for
    quoting.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the file name with a line break.
 
    The command is intended for use when quoting parts from file with
    the walkthrough commands: \l {printline-command} {\\printline}, \l
    {printto-command} {\\printto}, \l {printuntil-command}
    {\\printuntil}, \l {skipline-command} {\\skipline}, \l
    {skipto-command} {\\skipto}, \l {skipuntil-command}
    {\\skipuntil}. This enables you to quote specific portions of a
    file.
 
    \badcode *
    /\1!
       The whole application is contained within
       the \c main() function:
 
       \quotefromfile examples/main.cpp
 
       \skipto main
       \printuntil app(argc, argv)
 
       First we create a QApplication object using
       the \c argc and \c argv parameters.
 
       \skipto QPushButton
       \printuntil resize
 
       Then we create a QPushButton, and give it a reasonable
       size using the QWidget::resize() function.
 
       ...
    \1/
    \endcode
 
    QDoc remembers which file it is quoting from, and the current
    position in that file (see \l {file} {\\printline} for more
    information). There is no need to "close" the file.
 
    See also \l {quotefile-command} {\\quotefile}, \l {code-command}
    {\\code} and \l {dots} {\\dots}.
 
    \target printline-command
    \section1 \\printline
 
    The \\printline command expands to the line from the current
    position.
 
    To ensure that the documentation remains synchronized with the
    source file, a substring of the line must be specified as an
    argument to the command. Note that the command considers the rest
    of the line as part of its argument, make sure to follow the
    substring with a line break.
 
    The line from the source file is rendered as a separate paragraph,
    using a monospace font and the standard indentation. The code is
    shown verbatim.
 
    \badcode *
    /\1!
       There has to be exactly one QApplication object
       in every GUI application that uses Qt.
 
       \quotefromfile examples/main.cpp
 
       \printline QApplication
 
       This line includes the QApplication class
       definition. QApplication manages various
       application-wide resources, such as the
       default font and cursor.
 
       \printline QPushButton
 
       This line includes the QPushButton class
       definition. The QPushButton widget provides a command
       button.
 
       \printline main
 
       The main function...
    \1/
    \endcode
 
    \target file
 
    QDoc reads the file sequentially. To move the current position
    forward you can use either of the \l {skipline-command}
    {\\skip...} commands. To move the current position backward, you
    can use the \l {quotefromfile-command} {\\quotefromfile} command
    again.
 
    \target substring
 
    If the substring argument is surrounded by slashes it is
    interpreted as a \l {QRegularExpression}{regular expression}.
 
    \badcode *
    /\1!
       \quotefromfile examples/mainwindow.cpp
 
       \skipto closeEvent
       \printuntil /^\}/
 
       Close events are sent to widgets that the users want to
       close, usually by clicking \c File|Exit or by clicking
       the \c X title bar button. By reimplementing the event
       handler, we can intercept attempts to close the
       application.
    \1/
    \endcode
 
    (\l {widgets/scribble} {The complete example file...})
 
    The regular expression \c /^\}/ makes QDoc print until the first
    '}' character occurring at the beginning of the line without
    indentation. /.../ encloses the regular expression, and '^' means
    the beginning of the line. The '}' character must be escaped since
    it is a special character in regular expressions.
 
    QDoc will emit a warning if the specified substring or regular
    expression cannot be located, i.e. if the source code has changed.
 
    See also \l {printto-command} {\\printto} and \l
    {printuntil-command} {\\printuntil}.
 
    \target printto-command
    \section1 \\printto
 
    The \\printto command expands to all the lines from the current
    position up to and \e excluding the next line containing a given
    substring.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the substring with a line break. The
    command also follows the same conventions for \l {file}
    {positioning} and \l {substring} {argument} as the \l
    {printline-command} {\\printline} command.
 
    The lines from the source file are rendered in a separate
    paragraph, using a monospace font and the standard
    indentation. The code is shown verbatim.
 
    \badcode *
    /\1!
       The whole application is contained within the
       \c main() function:
 
       \quotefromfile examples/main.cpp
       \printto hello
 
       First we create a QApplication object using the \c argc and
       \c argv parameters...
    \1/
    \endcode
 
    See also \l {printline-command} {\\printline} and \l
    {printuntil-command} {\\printuntil}.
 
    \target printuntil-command
    \section1 \\printuntil
 
    The \\printuntil command expands to all the lines from the current
    position up to and \e including the next line containing a given
    substring.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the substring with a line break. The
    command also follows the same conventions for \l {file}
    {positioning} and \l {substring} {argument} as the \l
    {printline-command} {\\printline} command.
 
    If \\printuntil is used without an argument, it expands to all the
    lines from the current position to the end of the quoted file.
 
    The lines from the source file are rendered in a separate
    paragraph, using a monospace font and the standard
    indentation. The code is shown verbatim.
 
    \badcode *
    /\1!
       The whole application is contained within the
       \c main() function:
 
       \quotefromfile examples/main.cpp
       \skipto main
       \printuntil hello
 
       First we create a QApplication object using the
       \c argc and \c argv parameters, then we create
       a QPushButton.
    \1/
    \endcode
 
    See also \l {printline-command} {\\printline} and \l
    {printto-command} {\\printto}.
 
    \target skipline-command
    \section1 \\skipline
 
    The \\skipline command ignores the next non-blank line in the
    current source file.
 
    Doc reads the file sequentially, and the \\skipline command is
    used to move the current position (omitting a line of the source
    file). See the remark about \l {file} {file positioning} above.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the substring with a line break. The
    command also follows the same conventions for \l {substring}
    {argument} as the \l {printline-command} {\\printline} command,
    and it is used in conjunction with the \l {quotefromfile-command}
    {\\quotefromfile} command.
 
    \badcode *
    /\1!
       QPushButton is a GUI push button that the user
       can press and release.
 
       \quotefromfile examples/main.cpp
       \skipline QApplication
       \printline QPushButton
 
       This line includes the QPushButton class
       definition. For each class that is part of the
       public Qt API, there exists a header file of
       the same name that contains its definition.
    \1/
    \endcode
 
 
    See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
    {\\skipuntil} and \l {dots} {\\dots}.
 
    \target skipto-command
    \section1 \\skipto
 
    The \\skipto command ignores all the lines from the current
    position up to and \e excluding the next line containing a given
    substring.
 
    QDoc reads the file sequentially, and the \\skipto command is used
    to move the current position (omitting one or several lines of the
    source file). See the remark about \l {file} {file positioning}
    above.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the substring with a line break.
 
    The command also follows the same conventions for \l {substring}
    {argument} as the \l {printline-command} {\\printline} command,
    and it is used in conjunction with the \l {quotefromfile-command}
    {\\quotefromfile} command.
 
    \badcode *
    /\1!
       The whole application is contained within
       the \c main() function:
 
       \quotefromfile examples/main.cpp
       \skipto main
       \printuntil }
 
       First we create a QApplication object. There
       has to be exactly one such object in
       every GUI application that uses Qt. Then
       we create a QPushButton, resize it to a reasonable
       size ...
    \1/
    \endcode
 
    See also \l {skipline-command} {\\skipline}, \l
    {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
 
    \target skipuntil-command
    \section1 \\skipuntil
 
    The \\skipuntil command ignores all the lines from the current
    position up to and \e including the next line containing a given
    substring.
 
    QDoc reads the file sequentially, and the \\skipuntil command is
    used to move the current position (omitting one or several lines
    of the source file). See the remark about \l {file} {file
    positioning} above.
 
    The command considers the rest of the line as part of its
    argument, make sure to follow the substring with a line break.
 
    The command also follows the same conventions for \l {substring}
    {argument} as the \l {printline-command} {\\printline} command,
    and it is used in conjunction with the \l {quotefromfile-command}
    {\\quotefromfile} command.
 
    \badcode *
    /\1!
       The first thing we did in the \c main() function
       was to create a QApplication object \c app.
 
       \quotefromfile examples/main.cpp
       \skipuntil show
       \dots
       \printuntil }
 
       In the end we must remember to make \c main() pass the
       control to Qt. QCoreApplication::exec() will return when
       the application exits...
    \1/
    \endcode
 
    See also \l {skipline-command} {\\skipline}, \l {skipto-command}
    {\\skipto} and \l {dots} {\\dots}.
 
    \target dots-command
    \section1 \\dots
 
    The \\dots command indicates that parts of the source file have
    been omitted when quoting a file.
 
    The command is used in conjunction with the \l
    {quotefromfile-command} {\\quotefromfile} command, and should be
    stated on its own line. The dots are rendered on a new line, using
    a monospace font.
 
    \badcode *
    /\1!
       \quotefromfile examples/main.cpp
       \skipto main
       \printuntil {
       \dots
       \skipuntil exec
       \printline }
    \1/
    \endcode
 
    The default indentation is 4 spaces, but this can be adjusted
    using the command's optional argument.
 
    \badcode *
    /\1!
        \dots 0
        \dots
        \dots 8
        \dots 12
        \dots 16
    \1/
    \endcode
 
    See also \l {skipline-command} {\\skipline}, \l {skipto-command}
    {\\skipto} and \l {skipuntil-command} {\\skipuntil}.
 
    \target snippet-command
    \section1 \\snippet
 
    The \\snippet command causes a code snippet to be included
    verbatim as preformatted text, which may be syntax highlighted.
 
    Each code snippet is referenced by the file that holds it and by
    a unique identifier for that file. Snippet files are typically
    stored in a \c{snippets} directory inside the documentation
    directory (for example, \c{$QTDIR/doc/src/snippets}).
 
    For example, the following documentation references a snippet in a
    file residing in a subdirectory of the documentation directory:
 
           \code
           \snippet snippets/textdocument-resources/main.cpp Adding a resource
           \endcode
 
    The text following the file name is the unique identifier for the
    snippet. This is used to delimit the quoted code in the relevant
    snippet file, as shown in the following example that corresponds to
    the above \c{\snippet} command:
 
    \code
    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));
 
//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...
    \endcode
 
    By default, QDoc looks for \c{//!} as a code snippet marker.
    For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt}
    files, \c {#!} is detected. Finally, \c{<!--} is accepted in
    \c{.html}, \c{.qrc}, \c{.ui}, \c{.xml}, and \c{.xq} files.
 
    QDoc normalizes snippet indentation by comparing the snippet-marker's
    space-based indentation against the snippet's minimum content indentation
    (ignoring Qt-macros, blank lines, and full-line comments). It then
    automatically un-indents the snippet body to whichever is smaller,
    ensuring the generated code always preserves its natural structure
    regardless of where the markers sit. Under-indented markers are left
    untouched.
 
    \note QDoc only handles space characters for indentation normalization,
    not tabs or other whitespace. For best results, use consistent space-based
    indentation in source files containing snippets.
 
    \target codeline-command
    \section1 \\codeline
 
    The \\codeline command inserts a blank line of preformatted
    text. It is used to insert gaps between snippets without closing
    the current preformatted text area and opening a new one.
 
*/
 
 
/*!
    \page 08-qdoc-commands-creatinglinks.html
    \previouspage Including External Code
    \nextpage Including Images
 
    \title Creating Links
 
    These commands are for creating hyperlinks to classes, functions,
    examples, and other targets.
 
    \target l-command
    \section1 \\l (link)
 
    The \\l link command is used to create a hyperlink to many
    different kinds of targets. The command's general syntax is:
 
    \code
      \l [ link criteria ] { link target } { link text }
    \endcode
 
    ...where the \c {link criteria} in square brackets are optional
    but may be required when the \c {link target} is ambiguous. See
    \l {Fixing Ambiguous Links} below.
 
    You can use the \\l command to link to:
 
    \list
 
        \li an external page:
 
            \badcode
            An URL with a custom link text:
            \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
 
            An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.
            \endcode
 
            Renders as:
 
            An URL with a custom link text:
            \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
 
            An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.
 
            See also \l {externalpage-command}{\\externalpage}.
 
        \li a documentation page. The link target can be:
 
            \list
            \li the page title specified with the \l {title-command} {\\title}
                command:
 
                \badcode
                    Here is a link with a custom link text:
                    \l {Getting Started with QDoc}{QDoc - Getting Started}.
 
                    Here is a link with a link text that is the same as the link
                    target: \l {Getting Started with QDoc}.
                \endcode
 
                Renders as:
 
                Here is a link with a custom link text:
                \l {Getting Started with QDoc}{QDoc - Getting Started}.
 
                Here is a link with a link text that is the same as link target:
                \l {Getting Started with QDoc}.
 
            \li the page file name specified with the \l {page-command} {\\page}
                command:
 
                \badcode
                \page 08-qdoc-commands-creatinglinks.html
                \title Creating Links
 
                These commands are for creating hyperlinks to classes, functions,
                examples, and other targets.
 
                ...
 
                The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
                explains how to create links with QDoc.
                \endcode
 
                Renders as:
 
                The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
                article explains how to create links with QDoc.
 
            \li the page with a \l {keyword-command} {\\keyword} command.
            \endlist
 
        \li a particular anchor section within a document. The link target can be:
 
            \list
            \li a section title specified with one of the
                \l{section-commands} {Section commands}:
 
                \badcode
                    Here is a link to a QDoc Commands section of the Writing
                    Documentation topic:
                    \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
 
                    If you have unique section titles across your documentation
                    project, you can use the section title as a target without
                    the need to add the topic title:
                    \l {QDoc Commands}.
                \endcode
 
                Renders as:
 
                Here is a link to a QDoc Commands section of the Writing
                Documentation topic:
                \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
 
                If you have unique section titles across your documentation
                project, you can use the section title as a target without the
                need to add the topic title:
                \l {QDoc Commands}.
 
            \li an anchor defined with a \l {target-command}{\\target} command:
                \badcode
                    \target assertions
 
                    Assertions make some statement about the text at the
                    point where they occur in the regexp, but they do not
                    match any characters.
 
                    ...
 
                    Regexps are built up from expressions, quantifiers, and
                    \l {assertions} {assertions}.
 
                \endcode
 
            \endlist
 
        \li an API item. Target links can be:
 
            \list
                \li \c {\l QWidget} - The name of a class documented with the
                    \l {class-command} {\\class} or
                    \l {qmltype-command}{\\qmltype} command.
 
                \li \c {\l QWidget::sizeHint()} - The signature of a function
                    without parameters. If a matching function without
                    parameters can't be found, the link is satisfied with the
                    first matching function found.
 
                \li \c {\l QWidget::removeAction(QAction* action)} - The
                signature of a function with parameters. If an exact match is
                not found, the link is not satisfied and QDoc reports a
                \e {Can't link to...} error.
 
                \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
                {\\headerfile} command.
 
            \endlist
        \li an example. The target link is the example title or a relative path
            used in an \l {example-command} {\\example} command:
 
                \badcode *
                /\1!
                    \example widgets/imageviewer
                    \title ImageViewer Example
                    \brief Shows how to combine QLabel and QScrollArea
                    to display an image.
 
                    ...
                \1/
 
                ...
 
                See the example: \l widgets/imageviewer
                \endcode
    \endlist
 
    If the link target is equivalent to the link text, you can omit the second
    argument.
 
    For example, if you have documentation like:
 
    \badcode *
    /\1!
        \target assertions
 
        Assertions make some statement about the text at the
        point where they occur in the regexp, but they do not
        match any characters.
 
        ...
 
        Regexps are built up from expressions, quantifiers, and
        \l {assertions} {assertions}.
    \1/
    \endcode
 
    You can simplify this as follows:
 
    \badcode *
    /\1!
        \target assertions
 
        Assertions make some statement about the text at the
        point where they occur in the regexp, but they do not
        match any characters.
 
        ...
 
        Regexps are built up from expressions, quantifiers, and
        \l assertions.
    \1/
    \endcode
 
    For the one-parameter version, the braces can often be omitted.
 
    QDoc also tries to make a link out of any word that doesn't
    resemble a normal English word, for example, Qt class names or
    functions, like QWidget or QWidget::sizeHint(). In these cases,
    the \\l command can actually be omitted, but by using the command,
    you ensure that QDoc will emit a warning if it cannot find the
    link target. In addition, if you only want the function name to
    appear in the link, you can use the following syntax:
 
    \list
        \li \c {\l {QWidget::} {sizeHint()}}
    \endlist
 
    \section2 Fixing Ambiguous Links
 
    Because of the modularization of Qt beginning with Qt 5.0, The
    possibility that QDoc will have to deal with ambiguous links has
    increased. An ambiguous link is one that has a matching target in
    more than one Qt module, for example, the same section title can appear in
    more than one Qt module, or the name of a C++ class in one module
    can also be the name of a QML type in another module. A real
    example in Qt5 is the name Qt itself. Qt is the name of both a C++
    namespace in QtCore and a QML type in QtQml.
 
    Suppose we want to link to the \l {Qt} {Qt C++ namespace}.  At the
    time QDoc generated this HTML page, that link was correct.  Does
    it still go to the C++ namespace? Qdoc generated that link from
    this link command:
 
    \list
        \li \c {\l {Qt} {Qt C++ namespace}}
    \endlist
 
    Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}.
    At the time QDoc generated this HTML page, that link was also
    correct, but we had to use this link command:
 
    \list
        \li \c {\l [QML] {Qt} {Qt QML type}}
    \endlist
 
    The \e {QML} in \e {square brackets} tells QDoc to accept a
    matching target only if the target is on a QML page. Qdoc actually
    finds the C++ namespace target first, but since that target is on
    a C++ page, QDoc ignores it and keeps looking until it finds the
    same target on a QML page.
 
    Without the guidance in the \e{\\l command} in the optional \e
    {square bracket} argument, QDoc links to the first matching target
    it finds. QDoc can't warn that the link was ambiguous in such
    cases because it doesn't know that another matching target exists.
 
    \section2 What arguments can appear in square brackets?
 
    A link command with square bracket argument has the following syntax:
    \list
    \c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}}
    \endlist
 
    The \e {square bracket} argument is only allowed in the \c {\l
    (link)} command. The example above shows how \c QML is used as the
    \e {square brackets} argument to force QDoc to match a QML target.
    Most often, this will be a QML type, but it can also be a QML
    member function of property.
 
    In the example, QDoc didn't need a \e {square bracket} argument to
    find the Qt C++ namespace page, because that one was the first
    matching target QDoc found anyway. However, to force QDoc to find
    a C++ target when a matching QML target gets in the way, \c CPP
    can be used as the \e {square bracket} argument. For example:
 
    \list
        \li \c {\l [CPP] {Qt} {Qt C++ namespace}}
    \endlist
 
    ...will force QDoc to ignore the Qt QML type and continue
    searching until it matches the Qt C++ namespace.
 
    If the link target is neither a C++ nor a QML entity, \c {DOC} can
    be used as the \e {square bracket} argument to prevent QDoc from
    matching either of those. At this writing, there were no cases of
    ambiguous links where using \c {DOC} was required.
 
    Often, the documentor knows which Qt module the link target is
    in. When the module name is known, use the module name as the \e
    {square bracket} argument. In the example above, if we know that
    the QML type named Qt is located in the QtQml module, we can write
    the link command like this:
 
    \list
        \li \c {\l [QtQml] {Qt} {Qt QML type}}
    \endlist
 
    When a module name is used as the \e {square bracket} argument,
    QDoc will search for the link target in that module only. This
    makes searching for link targets more efficient.
 
    Finally, the module name and entity type arguments can be
    combined, separated by a blank, so something like this is also
    allowed:
 
    \list
        \li \c {\l [CPP QtQml] {Window} {C++ class Window}}
    \endlist
 
    As of this writing, there were no cases where combining the two
    was required.
 
    See also \l {sa-command} {\\sa}, \l {target-command} {\\target},
    and \l {keyword-command} {\\keyword}.
 
 
    \target sa-command
    \section1 \\sa (see also)
 
    The \\sa command defines a list of links that will be rendered in
    a separate "See also" section at the bottom of the documentation
    unit.
 
    The command takes a comma-separated list of links as its
    argument. If the line ends with a comma, you can continue
    the list on the next line. The general syntax is:
 
    \code
    \sa {the first link}, {the second link},
        {the third link}, ...
    \endcode
 
    QDoc will automatically try to generate "See also" links
    interconnecting a property's various functions. For example, a
    setVisible() function will automatically get a link to visible()
    and vice versa.
 
    In general, QDoc will generate "See also" links that interconnect
    the functions that access the same property. It recognizes four
    different syntax versions:
 
    \list
      \li \c property()
      \li \c setProperty()
      \li \c isProperty()
      \li \c hasProperty()
    \endlist
 
    The \\sa command supports the same kind of links as the \l
    {l-command} {\\l} command.
 
    \badcode *
    /\1!
        Appends the actions \a actions to this widget's
        list of actions.
 
        \sa removeAction(), QMenu, addAction()
    \1/
    void QWidget::addActions(QList<QAction *> actions)
    {
        ...
    }
    \endcode
 
    See also \l {l-command} {\\l}, \l {target-command} {\\target} and
    \l {keyword-command} {\\keyword}.
 
 
    \target target-command
    \section1 \\target
 
    The \\target command names a place in the documentation that you
    can link to using the \l {l-command} {\\l (link)} and \l
    {sa-command} {\\sa (see also)} commands.
 
    \e{The text up to the line break becomes the target name}. Be sure
    to follow the target name with a line break. Curly brackets are not
    required around the target name, but they may be required when the
    target name is used in a link command. See below.
 
    \badcode *
    /\1!
        \target capturing parentheses
        \section1 Capturing Text
 
        Parentheses allow us to group elements together so that
        we can quantify and capture them.
 
        ...
    \1/
    \endcode
 
    The target name \e{capturing parentheses} can be linked to
    in the following way:
 
    \list
      \li \c {\l {capturing parentheses}}
    \endlist
 
    \note The brackets in the link example are required because the
    target name contains spaces.
 
    \section2 \\target in a \\table
    When you use the \\target command in a table, make sure that the
    \\target command follows a \l {li-command}{\\li}-command (table
    cell), as some generators only support targets to an individual cell,
    not to a whole row.
    Moreover, ensure that it's either on a separate line, or the last content
    that occurs in the line it's in. This is due to how the \\target
    command works; it consumes anything up to the next line break as
    its parameter. In other words, if you have a table and need a
    \\target within it, make sure that it follows the following
    structure:
 
    \badcode
    \table
        \row
            \li \target my-target
            My text goes here.
            \li This is my next table cell.
    \endtable
    \endcode
 
    See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l
    {keyword-command} {\\keyword}.
 
    \target keyword-command
    \section1 \\keyword
 
    The \\keyword command names a place in the documentation that you
    can link to using the \l {l-command} {\\l (link)} and \l
    {sa-command} {\\sa (see also)} commands. It also adds the keyword
    and the location to generated indices.
 
    The \\keyword command is like the \l {target-command} {\\target}
    command, except that when linking to a keyword, by default the link
    goes to the top of the QDoc comment (topic) the \\keyword appears in.
 
    If you want to create a keyword for a \c section unit within a
    topic, add the \\keyword directly above the section title:
 
    \badcode
    \keyword debug
    \section1 Debug command line option (--debug)
    ...
    \endcode
 
    Unlike \\target, keywords are registered in indices of generated
    offline documentation files (.qch). This allows users to look up the
    location by keyword, for instance, in
    \l[QtAssistant]{Searching for Keywords}{Qt Assistant's Index Search},
    and makes the keyword accessible in \QC's context help.
 
    Keywords must be unique over all the documents processed during
    the QDoc run. The command uses the rest of the line as its
    argument. Be sure to follow the keyword with a line break.
 
 
    \badcode *
    /\1!
        \class QRegularExpression
        \reentrant
        \brief The QRegularExpression class provides pattern
               matching using regular expressions.
        \ingroup tools
        \ingroup misc
        \ingroup shared
 
        \keyword regular expression
 
        Regular expressions, or "regexps", provide a way to
        find patterns within text.
 
        ...
    \1/
    \endcode
 
    The location marked with the keyword can be linked to with:
 
    \badcode *
    /\1!
        When a string is surrounded by slashes, it is
        interpreted as a \l {regular expression}.
    \1/
    \endcode
 
    If the keyword text contains spaces, the brackets are required.
 
    See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see
    also)} and \l {target-command} {\\target}.
 
*/
 
 
/*!
    \page 09-qdoc-commands-includingimages.html
    \previouspage Creating Links
    \nextpage Tables and Lists
 
    \title Including Images
 
    The graphic commands makes it possible to include images in the
    documentation. The images can be rendered as separate paragraphs,
    or within running text.
 
    \target image-command
    \section1 \\image
 
    The \\image command expands to the image specified by its first
    argument, and renders it centered as a separate paragraph.
 
    The command takes two arguments. The first argument is the name of
    the image file. The second argument is a description of what
    the image contains, and is used for the HTML \c alt attribute.
    Its contents is read aloud by screen readers, and its use is therefore
    strongly recommended for accessibility purposes. It may also be used by
    browsers that don't support images, like the Lynx text browser. You
    can also set the \l {usealttextastitle-variable} {usealttextastitle}
    variable to make QDoc generate a \e title attribute for the image, which
    commonly is rendered by graphical text browsers as a tooltip when the user
    hovers the mouse over the image.
 
    While QDoc is quite forgiving, you should wrap both the file name and the
    description in curly braces, like so:
    \badcode
    \image {Bandit.png} {A Golden Retriever holding a bag of coffee in its mouth}
    \endcode
    This syntax is the most explicit and should always give the expected result.
    If not, be sure to follow the file name or the description with a line break.
    Curly brackets are required if the description argument spans multiple lines.
    If the description is wrapped in double quotes, QDoc will remove them before
    generating output. Special characters may be replaced with the corresponding
    HTML entity code in QDoc's HTML output.
 
    \badcode *
    /\1!
        Qt is a C++ toolkit for cross-platform GUI application development.
 
        \image {happyguy.jpg} {Happy guy}
 
        Qt provides single-source portability across Microsoft
        Windows, macOS, Linux, and all major commercial Unix
        variants. It is also available for embedded devices.
    \1/
    \endcode
 
    See also \l {inlineimage-command} {\\inlineimage} and \l
    {caption-command} {\\caption}.
 
    \target inlineimage-command
    \section1 \\inlineimage
 
    The \\inlineimage command expands to the image specified by its
    argument. The image is rendered inline with the rest of the text.
 
    The command takes two arguments. The first argument is the name of
    the image file. The second argument is optional and is a simple
    description of the image within braces {}, equivalent to the HTML
    alt="" in an image tag. The description is used for tooltips, and
    for when a browser doesn't support images, like the Lynx text browser.
 
    The most common use of the \\inlineimage command is in lists and
    tables. Here is an example of including inline images in a list:
 
    \badcode *
    /\1!
        \list 1
          \li \inlineimage happy.gif {Oh so happy, I am a caption!}
          \li \inlineimage happy.gif Oh so happy, but I'm not a caption.
        \endlist
    \1/
    \endcode
 
    Here is an example of including inline images in a table:
 
    \badcode *
    /\1!
        \table
        \header
            \li Qt
            \li Qt Creator
        \row
            \li \inlineimage happy.gif {Oh so happy!}
            \li \inlineimage happy.gif Oh so happy!
        \row
            \li \inlineimage happy.gif Oh so happy!
            \li \inlineimage happy.gif {Oh so happy!}
        \endtable
    \1/
    \endcode
 
    The command can also be used to insert an image inline with the
    text.
 
    \badcode *
    /\1!
        \inlineimage training.jpg {Qt Training} The Qt Programming course is
        offered as a five day Open Enrollment Course. The classes are open to
        the public. Although the course is open to anyone who wants to learn,
        attendees should have significant experience in C++ development to
        derive maximum benefit from the course.
    \1/
    \endcode
 
    See also \l {image-command} {\\image} and \l {caption-command} {\\caption}.
 
    \target caption-command
    \section1 \\caption
 
    The \\caption command provides a caption for an image.
 
    The command takes all the text up to the end of the paragraph to
    be the caption. Experiment until you get the effect you want.
 
    \badcode *
    /\1!
      \table 100%
        \row
          \li \image windows-pushbutton.png
             \caption The QPushButton widget provides a command button.
          \li \image windows-toolbutton.png
             \caption The QToolButton class provides a quick-access button to commands
             or options, usually used inside a QToolBar.
       \endtable
    \1/
    \endcode
 
    See also \l {image-command} {\\image} and \l {inlineimage-command}
    {\\inlineimage}
*/
 
 
/*!
    \page 10-qdoc-commands-tablesandlists.html
    \previouspage Including Images
    \nextpage Special Content
 
    \title Tables and Lists
 
    These commands enable creating lists and tables. A list is
    rendered left aligned as a separate paragraph. A table is rendered
    centered as a separate paragraph. The table width depends on the
    width of its contents.
 
    \target table-command
    \section1 \\table
 
    The \\table and \\endtable commands delimit the contents of a
    table.
 
    The command accepts a single argument specifying the table's width
    as a percentage of the page width:
 
    \badcode *
    /\1!
       \table 100 %
 
          ...
 
       \endtable
    \1/
    \endcode
 
    The code above ensures that the table will fill all available
    space. If the table's width is smaller than 100 %, the table will
    be centered in the generated documentation.
 
    A table can contain headers, rows and columns. A row starts with a
    \l {row-command} {\\row} command and consists of cells, each of which
    starts with an \l {li-command} {\\li} command. There is also a \l
    {header-command} {\\header} command which is a special kind of row
    that has a special format.
 
    \badcode *
    /\1!
       \table
       \header
           \li Qt Core Feature
           \li Brief Description
       \row
           \li \l {Signal and Slots}
           \li Signals and slots are used for communication
              between objects.
       \row
           \li \l {Layout Management}
           \li The Qt layout system provides a simple
              and powerful way of specifying the layout
              of child widgets.
       \row
           \li \l {Drag and Drop}
           \li Drag and drop provides a simple visual
              mechanism which users can use to transfer
              information between and within applications.
       \endtable
    \1/
    \endcode
 
    You can also make cells span several rows and columns. For
    example:
 
    \badcode *
    /\1!
       \table
       \header
           \li {3,1} This header cell spans three columns,
              but only one row.
       \row
           \li {2, 1} This table cell spans two columns,
              but only one row
           \li {1, 2} This table cell spans only one column,
           but two rows.
       \row
           \li A regular table cell
           \li A regular table cell
       \endtable
    \1/
    \endcode
 
    See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}.
 
    \target header-command
    \section1 \\header
 
    The \\header command indicates that the following table cells are
    the current table's column headers.
 
    The command can only be used within the \l{table-command}
    {\\table...\\endtable} commands. A header can contain several
    cells. A cell is created with the \l {li-command} {\\li} command.
 
    A header cell's text is centered within the table cell and
    rendered using a bold font.
 
    \badcode *
    /\1!
       \table
       \header
           \li Qt Core Feature
           \li Brief Description
       \row
           \li \l {Signal and Slots}
           \li Signals and slots are used for communication
              between objects.
       \endtable
    \1/
    \endcode
 
    See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}.
 
    \target row-command
    \section1 \\row
 
    The \\row command begins a new row in a table. The \l {li-command}
    {\\li items} that belong in the new row will immediately follow the
    \\row.
 
    The command can only be used within the \l{table-command}
    {\\table...\\endtable} commands. A row can contain several
    cells. A cell is created with the \l {li-command} {\\li} command.
 
    The background cell color of each row alternates between two
    shades of grey, making it easier to distinguish the rows from each
    other. The cells' contents is left aligned.
 
    \badcode *
    /\1!
       \table
       \header
           \li Qt Core Feature
           \li Brief Description
       \row
           \li \l {Signal and Slots}
           \li Signals and slots are used for communication
              between objects.
       \row
           \li \l {Layout Management}
           \li The Qt layout system provides a simple
              and powerful way of specifying the layout
              of child widgets.
       \row
           \li \l {Drag and Drop}
           \li Drag and drop provides a simple visual
              mechanism which users can use to transfer
              information between and within applications.
       \endtable
    \1/
    \endcode
 
    See also \l {table-command} {\\table}, \l {header-command}
    {\\header}, and \l {li-command} {\\li}.
 
    \target value-command
    \section1 \\value
 
    The \\value command starts the documentation of a C++ enum item.
 
    The command's first argument is the value name. The value name may
    be preceded by an optional \e since clause enclosed in square
    brackets. The value description follows the value name. The description
    ends at the next blank line or \\value. The arguments are rendered in a
    table.
 
    \note To include images in the \\value description, use the
          \l {inlineimage-command}{\\inlineimage} command.
 
    Without a \e since clause, a \\value command could look like this:
 
    \code
    \value QtInfoMsg A message generated by the qInfo() function.
    \endcode
 
    The same command with a \e since clause would look like this:
 
    \code
    \value [since 5.5] QtInfoMsg A message generated by the qInfo() function.
    \endcode
 
    The documentation will be located in the associated class, header
    file or namespace documentation. See the \l {enum-command}
    {\\enum} documentation for an example.
 
    \note Since Qt 5.4, \\value command can also be used outside the
    \l {enum-command} {\\enum} topic. In this case, QDoc renders a
    two-column table listing the constant name (taken as-is from the
    first argument) and its description. This can be used, for
    example, in \l {qmlproperty-command}{\\qmlproperty} topic for
    documenting acceptable values for a QML enumeration property.
 
    See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
 
    \target omitvalue-command
    \section1 \\omitvalue
 
    The \\omitvalue command excludes a C++ enum item from the
    documentation.
 
    The command's only mandatory argument is the name of the enum item
    that will be omitted. If the enum item is followed by a single-line
    description, that is also omitted.
 
    See the \l {enum-command} {\\enum} documentation for an example.
 
    See also \l {enum-command} {\\enum} and \l {value-command}
    {\\value} \l {since-command}{\\since}
 
    \target list-command
    \section1 \\list
 
    The \\list and \\endlist commands delimit a list of items.
 
    Create each list item with the \l {li-command} {\\li} command. A
    list always contains one or more items. Lists can be nested. For
    example:
 
    \badcode *
    /\1!
        \list
            \li Qt Reference Documentation: Getting Started
            \list
                \li How to Learn Qt
                \li Installation
                \list
                    \li Qt/X11
                    \li Qt/Windows
                    \li Qt/Mac
                    \li Qt/Embedded
                \endlist
            \li Tutorial and Examples
            \endlist
        \endlist
    \1/
    \endcode
 
    The \\list command takes an optional argument providing
    alternative appearances for the list items.
 
    \badcode *
    /\1!
       \list
           \li How to Learn Qt
           \li Installation
           \li Tutorial and Examples
       \endlist
    \1/
    \endcode
 
    If you provide 'A' as an argument to the \\list command, the
    bullets are replaced with characters in alphabetical order:
 
    \list A
       \li How to Learn Qt
       \li Installation
       \li Tutorial and Examples
    \endlist
 
    If you replace 'A' with '1', the list items are numbered in
    ascending order:
 
    \list 1
       \li How to Learn Qt
       \li Installation
       \li Tutorial and Examples
    \endlist
 
    If you provide 'i' as the argument, the bullets are replaced with
    roman numerals:
 
    \list i
       \li How to Learn Qt
       \li Installation
       \li Tutorial and Examples
    \endlist
 
    Finally, you can make the list items appear with roman numbers
    following in ascending order if you provide 'I' as the optional
    argument:
 
    \list I
       \li How to Learn Qt
       \li Installation
       \li Tutorial and Examples
    \endlist
 
    You can also make the listing start at any character or number by
    simply provide the number or character you want to start at. For
    example:
 
    \badcode *
    /\1!
       \list G
           \li How to Learn Qt
           \li Installation
           \li Tutorial and Examples
       \endlist
    \1/
    \endcode
 
    See also \l {li-command} {\\li}.
 
    \target li-command
    \section1 \\li (table cell, list item)
 
    The \\li command marks a table cell or a list item. This command
    is only used in \l{table-command} {tables} and \l{list-command}
    {lists}.
 
    It considers everything as its argument until the next \\li command, until the
    next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist}
    command. See \l {table-command} {\\table} and \l {list-command} {\\list}
   for examples.
 
    If the command is used within a table, you can also specify
    how many rows or columns the item should span.
 
    \badcode *
    /\1!
       \table
       \header
           \li {3,1} This header cell spans three columns
              but only one row.
       \row
           \li {2, 1} This table item spans two columns
              but only one row
           \li {1, 2} This table item spans only one column,
           but two rows.
       \row
           \li A regular table item
           \li A regular table item
       \endtable
    \1/
    \endcode
 
    If not specified, the item will span one column and one row.
 
    See also \l {table-command} {\\table}, \l {header-command}
    {\\header}, and \l {list-command} {\\list}.
 
*/
 
 
/*!
    \page 11-qdoc-commands-specialcontent.html
    \previouspage Tables and Lists
    \nextpage Miscellaneous
 
    \title Special Content
 
    The document contents commands identify parts of the documentation,
    parts with a special rendering, conceptual meaning or
    function.
 
    \target quotation-command
    \section1 \\quotation
 
    The \\quotation and \\endquotation commands delimit a long quotation.
 
    The text in the delimited block is surrounded by
    \b{<blockquote>} and \b{</blockquote>} in the html output,
    e.g.:
 
    \badcode *
    /\1!
      Although the prospect of a significantly broader market is
      good news for Firstlogic, the notion also posed some
      challenges. Dave Dobson, director of technology for the La
      Crosse, Wisconsin-based company, said:
 
      \quotation
         As our solutions were being adopted into new
         environments, we saw an escalating need for easier
         integration with a wider range of enterprise
         applications.
      \endquotation
    \1/
    \endcode
 
    The text in the \b{\\quotation} block will appear in the generated HTML as:
 
    \badcode
    <blockquote>
      <p>As our solutions were being adopted into new environments,
      we saw an escalating need for easier integration with a wider
      range of enterprise applications.</p>
    </blockquote>
    \endcode
 
    The built-in style sheet for most browsers will render the
    contents of the <blockquote> tag with left and right
    indentations. The example above would be rendered as:
 
    \quotation
         As our solutions were being adopted into new
         environments, we saw an escalating need for easier
         integration with a wider range of enterprise
         applications.
    \endquotation
 
    But you can redefine the \b{<blockquote>} tag in your style.css file.
 
 
    \target note-command
    \section1 \\note
 
    The \\note command defines a new paragraph preceded by "Note:"
    in bold. The command takes a continuous paragraph as the argument,
    terminating after the end of the paragraph. The note command is only for
    shorter statements and not for longer multiline paragraphs.
 
    Similar to the \l{warning-command}{\\warning} command, the note is for
    short and important statements. See
    \l{https://wiki.qt.io/Qt_Writing_Guidelines}{Qt Writing Guidelines} for
    usage information.
 
    \target notranslate-command
    \section1 \\notranslate
 
    The \\notranslate command indicates that its argument is \b not to be translated,
    when the generated output is passed to a language translation service.
 
    Other commands (\qdoccmd {c}, \qdoccmd {tt}) have the same effect, but
    \\notranslate does not style its argument in any way.
 
    This command was introduced in QDoc version 6.10.
 
    \target brief-command
    \section1 \\brief
 
    The \\brief command introduces a one-sentence description of
    any of the \l{Topic Commands}.
 
    The brief text is used to introduce the documentation of the
    associated object, and in lists generated using the \l
    {generatelist-command} {\\generatelist} command and the \l
    {annotatedlist-command} {\\annotatedlist} command.
 
    The brief text will be displayed in the documentation
    for that particular topic.
 
    For example the boolean QWidget::isWindow property:
 
    \badcode *
    /\1!
       \property QWidget::isActiveWindow
       \brief Whether this widget's window is the active window.
 
       The active window is the window that contains the widget that
       has keyboard focus.
 
       When popup windows are visible, this property is \c true
       for both the active window \e and the popup.
 
       \sa activateWindow(), QApplication::activeWindow()
    \1/
    \endcode
 
    and the QWidget::geometry property
 
    \badcode *
    /\1!
       \property QWidget::geometry
       \brief The geometry of the widget relative to its parent and
       excluding the window frame.
 
       When changing the geometry, the widget, if visible,
       receives a move event (moveEvent()) and/or a resize
       event (resizeEvent()) immediately.
 
       ...
 
      \sa frameGeometry(), rect(), ...
    \1/
    \endcode
 
    When the \\brief command is used to describe a class, we recommend
    using a complete sentence like this:
 
    \badcode
    The <classname> class is|provides|contains|specifies...
    \endcode
 
    \warning Do not repeat your detailed description with the same sentence as
    the brief statement will be the first paragraph of the detailed
    description.
 
    \badcode *
    /\1!
       \class PreviewWindow
       \brief The PreviewWindow class is a custom widget
              displaying the names of its currently set
              window flags in a read-only text editor.
 
       The PreviewWindow class inherits QWidget. The widget
       displays the names of its window flags set with the
       setWindowFlags() function. It is also provided with a
       QPushButton that closes the window.
 
       ...
 
       \sa QWidget
    \1/
    \endcode
 
    Using \\brief in a \l{namespace-command}{\\namespace}:
 
    \badcode *
    /\1!
       \namespace Qt
 
       \brief The Qt namespace contains miscellaneous identifiers
       used throughout the Qt library.
    \1/
    \endcode
 
    Using \\brief in a \l{headerfile-command}{\\headerfile}:
 
    \badcode *
    /\1!
       \headerfile <QtGlobal>
       \title Global Qt Declarations
 
       \brief The <QtGlobal> header file provides basic
       declarations and is included by all other Qt headers.
 
       \sa <QtAlgorithms>
    \1/
    \endcode
 
    See also \l{property-command} {\\property}, \l{class-command}
    {\\class}, \l{namespace-command} {\\namespace} and
    \l{headerfile-command} {\\headerfile}.
 
    \target legalese-command
    \section1 \\legalese
 
    The \\legalese and \\endlegalese commands delimit a license agreement.
 
    In the generated HTML, the delimited text is surrounded by a \b
    {<div class="LegaleseLeft">} and \b {</div>} tags.
 
    An example of a license agreement enclosed in \\legalese
    and \\endlegalese:
 
    \badcode *
    /\1!
        \legalese
            Copyright 1996 Daniel Dardailler.
 
            Permission to use, copy, modify, distribute, and sell this
            software for any purpose is hereby granted without fee,
            provided that the above copyright notice appear in all
            copies and that both that copyright notice and this
            permission notice appear in supporting documentation, and
            that the name of Daniel Dardailler not be used in
            advertising or publicity pertaining to distribution of the
            software without specific, written prior permission. Daniel
            Dardailler makes no representations about the suitability of
            this software for any purpose. It is provided "as is"
            without express or implied warranty.
 
            Modifications Copyright 1999 Matt Koss, under the same
            license as above.
        \endlegalese
    \1/
    \endcode
 
    It will appear in the generated HTML as:
 
    \badcode
    <div class="LegaleseLeft">
       <p>Copyright 1996 Daniel Dardailler.</p>
       <p>Permission to use, copy, modify, distribute, and sell
       this software for any purpose is hereby granted without fee,
       provided that the above copyright notice appear in all
       copies and that both that copyright notice and this
       permission notice appear in supporting documentation, and
       that the name of Daniel Dardailler not be used in
       advertising or publicity pertaining to distribution of the
       software without specific, written prior permission. Daniel
       Dardailler makes no representations about the suitability of
       this software for any purpose. It is provided "as is"
       without express or implied warranty.</p>
 
       <p>Modifications Copyright 1999 Matt Koss, under the same
       license as above.</p>
    </div>
    \endcode
 
    If the \\endlegalese command is omitted, QDoc will process the
    \\legalese command but considers the rest of the documentation
    page as the license agreement.
 
    Ideally, the license text is located with the licensed code.
 
    Elsewhere, the documentation identified as \e{\\legalese} command
    can be accumulated using \l {generatelist-command} {\\generatelist}
    with \c {legalese} as the argument. This is useful for generating
    an overview of the license agreements associated with the source
    code.
 
    \note The output of the \c {\generatelist legalese} command includes
    the \\legalese texts in the current documentation project only. If
    the current documentation project depends on other modules, their
    license texts will not be listed.
 
    \target warning-command
    \section1 \\warning
 
    The \\warning command prepends "Warning:" to the command's
    argument, in bold font.
 
    \badcode *
    /\1!
       Qt::HANDLE is a platform-specific handle type
       for system objects. This is  equivalent to
       \c{void *} on Windows and macOS, and to
       \c{unsigned long} on X11.
 
       \warning Using this type is not portable.
    \1/
    \endcode
*/
 
 
/*!
    \page 12-0-qdoc-commands-miscellaneous.html
    \previouspage Special Content
    \nextpage The QDoc Configuration File
 
    \title Miscellaneous
 
    These commands provide miscellaneous functions connected to the
    visual appearance of the documentation, and to the process of
    generating the documentation.
 
    \target annotatedlist-command
    \section1 \\annotatedlist
 
    The \\annotatedlist command expands to a list of the members of a
    group, each member listed with its \e {brief} text. Below is an
    example from the Qt Reference Documentation:
 
    \badcode *
    /\1!
       ...
       \section1 Drag and Drop Classes
 
       These classes deal with drag and drop and the necessary mime type
       encoding and decoding.
 
       \annotatedlist draganddrop
    \1/
    \endcode
 
    This generates a list of all the C++ classes and/or QML types in
    the \e{draganddrop} group. A C++ class or QML type in the
    \e{draganddrop} group will have \e{\\ingroup draganddrop} in its
    \e{\\class} or \e{\\qmltype} comment.
 
    The group members are sorted in ascending order, based on
    user-visible name or title. Since QDoc 6.8, \\annotatedlist
    and \qdoccmd generatelist support also custom sorting.
 
    See also \qdoccmd generatelist and \l {Sorting group members}.
 
    \target cmakepackage-command
    \section1 \\cmakepackage
 
    Use the \\cmakepackage command to add CMake package information to classes
    and namespaces. This information will then appear in a table at the top of
    the class or namespace documentation page. For example:
 
    \badcode *
    /*!
        \namespace Foo
        \inheaderfile Bar
        \cmakepackage Baz
        \brief A namespace.
 
        ...
    \1/
    \endcode
 
    QDoc will output this as
 
    \quotation
        \raw HTML
            <h1 class="title">Foo Namespace</h1>
            <p>A namespace. <a>More...</a></p>
            <div class="table"><table class="alignedsummary">
            <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;Bar&gt;</span></td></tr>
            <tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Baz REQUIRED)<br/>target_link_libraries(mytarget PRIVATE Baz::Baz)</td></tr>
            </table></div>
        \endraw
    \endquotation
 
    \e{See also} \l{module-command}{\\module} and
    \l{cmakecomponent}{\\cmakecomponent}}
 
    \target cmakecomponent-command
    \section1 \\cmakecomponent
 
    Use the \\cmakecomponent command to add CMake component information to classes
    and namespaces. This information will then appear in a table at the top of
    the class or namespace documentation page. For example:
 
    \badcode *
    /*!
        \namespace Foo
        \inheaderfile Bar
        \cmakecomponent Baz
        \brief A namespace.
 
        ...
    \1/
    \endcode
 
    QDoc will output this as
 
    \quotation
        \raw HTML
            <h1 class="title">Foo Namespace</h1>
            <p>A namespace. <a>More...</a></p>
            <div class="table"><table class="alignedsummary">
            <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;Bar&gt;</span></td></tr>
            <tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 REQUIRED COMPONENTS Baz)<br/>target_link_libraries(mytarget PRIVATE Qt6::Baz)</td></tr>
            </table></div>
        \endraw
    \endquotation
 
    \e{See also} \l{module-command}{\\module} and
    \l{cmakepackage}{\\cmakepackage}}
 
    \target cmaketargetitem-command
    \section1 \\cmaketargetitem
 
    Use the \\cmaketargetitem command to override the \e {item} part of the
    CMake \c{target_link_libraries} information that's added to classes and
    namespaces. The command must be used in conjunction with the
    \l{module-command}{\\module} and \l{cmakecomponent}{\\cmakecomponent}}
    commands. For example:
 
    \badcode *
    /*!
        \namespace Foo
        \inheaderfile Bar
        \cmakecomponent Baz
        \cmaketargetitem Qt6::BazPrivate
        \brief A namespace.
 
        ...
    \1/
    \endcode
 
    QDoc will output this as
 
    \quotation
        \raw HTML
            <h1 class="title">Foo Namespace</h1>
            <p>A namespace. <a>More...</a></p>
            <div class="table"><table class="alignedsummary">
            <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;Bar&gt;</span></td></tr>
            <tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 REQUIRED COMPONENTS Baz)<br/>target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)</td></tr>
            </table></div>
        \endraw
    \endquotation
 
    \e{See also} \l{module-command}{\\module} and
    \l{cmakecomponent}{\\cmakecomponent}}
 
 
    \target qtcmakepackage-command
    \section1 \\qtcmakepackage
 
    Use the \\qtcmakepackage command to add CMake package information to classes
    and namespaces. This information will then appear in a table at the top of
    the class or namespace documentation page. For example:
 
    \badcode *
    /*!
        \namespace Foo
        \inheaderfile Bar
        \qtcmakepackage Baz
        \brief A namespace.
 
        ...
    \1/
    \endcode
 
    QDoc will output this as
 
    \quotation
        \raw HTML
            <h1 class="title">Foo Namespace</h1>
            <p>A namespace. <a>More...</a></p>
            <div class="table"><table class="alignedsummary">
            <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;Bar&gt;</span></td></tr>
            <tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 REQUIRED COMPONENTS Baz)</td></tr>
            </table></div>
        \endraw
    \endquotation
 
 
    \target qtcmaketargetitem-command
    \section1 \\qtcmaketargetitem
 
    Use the \\qtcmaketargetitem command to override the \e {item} part of the
    CMake \c{target_link_libraries} information that's added to classes and
    namespaces. The command must be used in conjunction with the
    \l{module-command}{\\module} and \l{qtcmakepackage}{\\qtcmakepackage}}
    commands.
 
    \e{See also} \l{module-command}{\\module} and
    \l{qtcmakepackage}{\\qtcmakepackage}}
 
 
    \target generatelist-command
    \section1 \\generatelist
 
    The \\generatelist command expands to a list of links to the
    documentation entities grouped with an \l {ingroup-command}
    {\\ingroup} command or entities that match one of the arguments
    listed below. An example from the Qt Reference Documentation:
 
    \badcode *
    /\1!
       \page classes.html
       \title All Classes
 
       For a shorter list that only includes the most
       frequently used classes, see \l{Qt's Main Classes}.
 
       \generatelist classes Q
    \1/
    \endcode
 
    This generates the \e {All Classes} page. The command accepts the
    following arguments:
 
    \section2 \c {<group-name>}
 
    With a group name as the only argument, QDoc lists all entities that
    use the \c {\ingroup <group-name>} command.
 
    \section3 Sorting group members
 
    When generating a list of group members, they are sorted in ascending
    order, based on user-visible name or title. Since QDoc 6.8, the default
    sort order can be modified:
 
    \badcode
        \generatelist [descending] changelogs
    \endcode
 
    Assuming the \e changelogs group consists of pages
    detailing changes in different versions, this generates the
    list in descending order (newest version first).
 
    \section4 Sort key
 
    Since QDoc 6.8, a custom sort key can be assigned to one or
    more group members using the \qdoccmd meta command:
 
    \badcode
        \meta sortkey {sort key}
    \endcode
 
    Sorting (ascending or descending) is then done based on
    these key(s), rather than user-visible titles.
 
    \note Any group member with a sort key is listed \e before
    members without a key (in the default ascending order). This
    allows raising individual group member(s) to the top of the
    list.
 
    \target table example
    \section2 \c annotatedclasses
 
    The \c annotatedclasses argument provides a table containing the
    names of all the classes, and a description of each class. Each
    class name is a link to the class's reference documentation. For
    example:
 
    \table
      \row
        \li QDial
    \li Rounded range control (like a speedometer or potentiometer)
      \row
        \li QDialog
    \li The base class of dialog windows
      \row
        \li QDir
        \li Access to directory structures and their contents
    \endtable
 
    A C++ class is documented with the \l {class-command} {\\class}
    command. The annotation for the class is taken from the argument
    of the class comment's \l {brief-command} {\\brief} command.
 
    \section2 \c annotatedexamples
 
    The \c annotatedexamples argument provides a complete list of all
    examples as a set of tables containing the titles of all the
    examples, and a description of each example. Each title is a
    link to the example's documentation.
 
    A separate table for each module (that has documented examples)
    is generated, provided that the module has defined a
    navigation.landingpage configuration variable. The \e landingpage
    variable is used as a title for a header that precedes each table.
 
    \section2 \c annotatedattributions
 
    The \c annotatedattributions argument provides a complete list of all
    attributions as a set of tables containing the titles of all the
    attributions, and a description of each attribution. Each title is a
    link to the attribution's page.
 
    A separate table for each module (that has attributions)
    is generated, provided that the module has defined a
    navigation.landingpage configuration variable. The \e landingpage
    variable is used as a title for a header that precedes each table.
 
    \target list example
    \section2 \c {classes <prefix>}
 
    The \c classes argument provides a complete alphabetical list of
    the classes. The second argument, \c{<prefix>}, is the common
    prefix for the class names. The class names will be sorted on the
    character that follows the common prefix. e.g. The common prefix
    for the Qt classes is \c Q. The common prefix argument is
    optional.  If no common prefix is provided, the class names will
    be sorted on their first character.
 
    Each class name becomes a link to the class's reference
    documentation. This command is used to generate the
    \e {All Classes} page this way:
 
    \badcode *
    /\1!
        \page classes.html
        \title All Classes
        \ingroup classlists
 
        \brief Alphabetical list of classes.
 
        This is a list of all Qt classes. For classes that
        have been deprecated, see the \l{Obsolete Classes}
        list.
 
        \generatelist classes Q
    \1/
    \endcode
 
    A C++ class is documented with the \l {class-command} {\\class}
    command.
 
    \section2 \c classesbymodule
 
    When this argument is used, a second argument is required, which
    specifies the module whose classes are to be listed. QDoc
    generates a table containing those classes. Each class is listed
    with the text of its \l{brief-command} {\\brief} command.
 
    For example, this command can be used on a module page as follows:
 
    \badcode *
    /\1!
        \page phonon-module.html
        \module Phonon
        \title Phonon Module
        \ingroup modules
 
        \brief Contains namespaces and classes for multimedia functionality.
 
        \generatelist{classesbymodule Phonon}
 
        ...
    \1/
    \endcode
 
    Each class that is a member of the specified module must be marked
    with the \l {inmodule-command} {\\inmodule} command in its \\class
    comment.
 
    \section2 \c qmltypesbymodule
 
    Similar to \c classesbymodule argument, but used for listing the
    QML types (excluding QML value types) from the QML module specified
    with the second argument.
 
    \note Support for this argument was introduced in QDoc 5.6.
 
    \section2 \c qmlvaluetypesbymodule
 
    Similar to \c qmltypesbymodule argument, but lists QML value
    types instead.
 
    \note Support for this argument was introduced in QDoc 6.7.
 
    \section2 \c functionindex
 
    The \c functionindex argument provides a complete alphabetical
    list of all the documented member functions. It is normally used
    only to generate the \e {Qt function index} page
    this way:
 
    \badcode *
    /\1!
        \page functions.html
        \title All Functions
        \ingroup funclists
 
        \brief All documented Qt functions listed alphabetically with a
        link to where each one is declared.
 
        This is the list of all documented member functions and global
        functions in the Qt API. Each function has a link to the
        class or header file where it is declared and documented.
 
        \generatelist functionindex
    \1/
    \endcode
 
    \section2 \c legalese
 
    The \c legalese argument tells QDoc to generate a list of licenses in
    the current documentation project. Each license is identified using
    the \l {legalese-command} {\\legalese} command.
 
    \section2 \c overviews
 
    The \c overviews argument is used to tell QDoc to generate a list
    by concatenating the contents of all the \l {group-command}
    {\\group} pages. Qt uses it to generate the \e {overviews} page
    this way:
 
    \badcode *
    /\1!
        \page overviews.html
 
        \title All Overviews and HOWTOs
 
        \generatelist overviews
    \1/
    \endcode
 
    \section2 \c attributions
 
    The \c attributions argument is used to tell QDoc to generate a list
    of attributions in the documentation.
 
    \section2 \c related
 
    The \c related argument is used in combination with the \l
    {group-command} {\\group} and \l {ingroup-command} {\\ingroup}
    commands to list all the overviews related to a specified
    group. For example, the page for the \e {Programming with Qt}
    page is generated this way:
 
    \badcode *
    /\1!
        \group qt-basic-concepts
        \title Programming with Qt
 
        \brief The basic architecture of the Qt cross-platform application and UI framework.
 
        Qt is a cross-platform application and UI framework for
        writing web-enabled applications for desktop, mobile, and
        embedded operating systems. This page contains links to
        articles and overviews explaining key components and
        techniuqes used in Qt development.
 
        \generatelist {related}
    \1/
    \endcode
 
    Each page listed on this group page contains the command:
 
    \code
        \ingroup qt-basic-concepts
    \endcode
 
    See also \qdoccmd {annotatedlist}.
 
    \target if-command
    \section1 \\if
 
    The \\if command and the corresponding \\endif command
    enclose parts of a QDoc comment that only will be included if
    the condition specified by the command's argument is true.
 
    The command reads the rest of the line and parses it as an C++ #if
    statement.
 
    \badcode *
    /\1!
       \if defined(opensourceedition)
 
       \note This edition is for the development of
       \l{Qt Open Source Edition} {Free and Open Source}
       software only; see \l{Qt Commercial Editions}.
 
       \endif
    \1/
    \endcode
 
    This QDoc comment will only be rendered if the \c
    opensourceedition preprocessor symbol is defined, and specified in
    the \l {defines-variable} {defines} variable in the configuration
    file to make QDoc process the code within #ifdef and #endif:
 
    \badcode
    defines = opensourceedition
    \endcode
 
    You can also define the preprocessor symbol manually on the
    command line. For more information see the documentation of the \l
    {defines-variable} {defines} variable.
 
    See also \l{endif-command} {\\endif}, \l{else-command} {\\else},
    \l {defines-variable} {defines} and \l {falsehoods-variable}
    {falsehoods}.
 
    \target endif-command
    \section1 \\endif
 
    The \\endif command and the corresponding \\if command
    enclose parts of a QDoc comment that will be included if
    the condition specified by the \l {if-command} {\\if} command's
    argument is true.
 
    For more information, see the documentation of the \l {if-command}
    {\\if} command.
 
    See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l
    {defines-variable} {defines} and \l {falsehoods-variable}
    {falsehoods}.
 
    \target else-command
    \section1 \\else
 
    The \\else command specifies an alternative if the
    condition in the \l {if-command} {\\if} command is false.
 
    The \\else command can only be used within \l {if-command}
    {\\if...\\endif} commands, but is useful when there is only two
    alternatives.
 
    \target include-command
    \section1 \\include
 
    The \\include command sends all or part of the file specified by
    its first argument to the QDoc input stream to be processed as a
    QDoc comment snippet.
 
    The command is useful when some snippet of commands or text is to
    be used in multiple places in the documentation. Use the \\include
    command wherever you want to insert a snippet into the documentation.
    The file containing the snippet to include, must be located under the
    path(s) listed in the \l{sourcedirs-variable}{sourcedirs} or
    \l{exampledirs-variable}{exampledirs} QDoc configuration variable.
    It can be either any source file parsed by QDoc (or even the same one
    where \\include command is used), or any other text file. To store
    snippets in a separate file that is not meant to be parsed by QDoc,
    use a file extension that is not listed in
    \l{sources.fileextensions-variable}{sources.fileextensions};
    for example, \c .qdocinc.
 
    The command can have one or more arguments. The first
    argument is always a file name. The contents of the file must be
    QDoc input, in other words, a sequence of QDoc commands and text, but
    without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters.
    If you want to include the entire named file, leave the second argument
    empty. If you want to include only part of the file, see the
    \l{2-argument-form}{two argument form} below. Here is an example
    of the one argument form:
 
    \badcode *
    /\1!
        \page corefeatures.html
        \title Core Features
 
        \include examples/signalandslots.qdocinc
        \include examples/objectmodel.qdocinc
        \include examples/layoutmanagement.qdocinc
    \1/
    \endcode
 
 
    \target 2-argument-form
    \section2 \\include filename snippet-identifier
 
    It is a waste of time to make a separate \c .qdocinc file for every
    QDoc include snippet you want to use in multiple places in the
    documentation, especially given that you probably have to put the
    copyright/license notice in every one of these files. If you
    have multiple snippets to be included, you can put them all in a
    single file and surround each one with:
 
    \badcode
    //! [snippet-id1]
 
    QDoc commands and text...
 
    //! [snippet-id1]
 
    //! [snippet-id2]
 
    More QDoc commands and text...
 
    //! [snippet-id2]
    \endcode
 
    Then you can use the two-argument form of the command:
 
    \badcode
        \include examples/signalandslots.qdocinc snippet-id2
        \include examples/objectmodel.qdocinc another-snippet-id
    \endcode
 
    The sequence of QDoc commands and text found between the two tags
    with the same name as the second argument is sent to the QDoc input
    stream. You can even have nested snippets.
 
    \note Snippet identifiers work also within documentation comment
    (\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a
    separate \c .qdocinc file. When processing a comment block, QDoc
    removes any \c {//!} comment lines from the generated output.
 
    \section2 Extra arguments
 
    Since QDoc 6.3, any further arguments passed to the \\include command
    are used for injecting strings into the included content. To inject a
    string to a specific location in the content, add a backslash followed
    by a digit (1..9). The digits correspond with the order of the argument
    list. Enclose arguments in curly braces to ensure that QDoc renders the
    entire argument, including possible whitespace characters, as you expect.
 
    \important Each additional argument (including the snippet ID) must be
               enclosed in braces. If you want to include the entire file,
               use an empty snippet ID: \c {{}}.
 
    For example, given the following snippet in a file \c includes.qdocinc:
 
    \badcode
    //! [usage]
    To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
    //! [usage]
    \endcode
 
    Then, the following \\include line:
 
    \badcode
    \include includes.qdocinc {usage} {detailed output} {Verbose}
    \endcode
 
    Renders
    \quotation
    To enable \e {detailed output}, select \uicontrol {Verbose} >
    \uicontrol Enable.
    \endquotation
 
    \target meta-command
    \section1 \\meta
 
    The \\meta command is used for adding metadata to documentation.
    The command has two arguments: the first argument is the name of the
    metadata attribute, and the second argument is the value for the attribute.
    Each argument should be enclosed in curly brackets, as shown in this
    example:
 
    \badcode *
    /\1!
        \example demos/coffee
        \title Coffee Machine
        \brief A Qt Quick application with a state-based custom user interface.
 
        \meta {tags} {quick,embedded,states,touch}
        \meta {category} {Application Examples}
    \1/
    \endcode
 
    A number of metadata attributes have a specific purpose:
 
    \b {Example Metadata}
 
    Another use for \\meta command is to include metadata (tags) in
    \l {example-command}{\\example} documentation. By default, QDoc
    generates example tags based on the example's \l {title-command}{\\title}
    and module name. These tags are displayed in Qt Creator's Welcome mode,
    helping users navigate the list of examples.
 
    Additional tags can be created with  \c {\meta {tag} {tag1}}
    or \c {\meta {tags} {tag1,[tag2,...]}}.
    For example:
 
    \badcode *
    /\1!
        \example helloworld
        \title Hello World Example
        \meta {tags} {tutorial,basic}
    \1/
    \endcode
 
    This would result in the following tags: \e {tutorial,basic,hello,world}.
    Common words such as \e example are ignored.
 
    \b {Excluding Examples}
 
    Marking an example \e broken will exclude it from the generated manifest
    file, effectively removing it from Qt Creator's Welcome mode.
 
    \badcode
    \meta {tag} {broken}
    \endcode
 
    \b {Example Install Paths}
 
    The \\meta command combined with an argument \c installpath specifies the
    location of an installed example. This value overrides the one that is set
    using the \c examplesinstallpath configuration variable.
 
    \badcode *
    /\1!
        \example helloworld
        \title Hello World Example
        \meta {installpath} {tutorials}
    \1/
    \endcode
 
    See also \l {examplesinstallpath}.
 
    \b {Status}
 
    A \c status argument for the \\meta command adds a custom status description
    for a \l {class-command}{\\class} or a \l {qmltype-command}{\\qmltype}. This
    description will then appear in a table at the top of the type reference page.
 
    \badcode *
    /\1!
        \class QNativeInterface::QAndroidApplication
        \meta {status} {Android-specific}
    \1/
    \endcode
 
    See also \l {Status}{status-related commands}.
 
    \target noautolist-command
    \section1 \\noautolist
 
    The \\noautolist command indicates that the annotated list of C++
    classes or QML types, which is automatically generated at the
    bottom of the C++ or QML module page should be omitted, because
    the classes or types have been listed manually. This command can
    also be used with the \l {group-command}{\\group} command to omit
    the list of group members, when they are listed manually.
 
    The command must stand on its own line. See \l {Qt Quick Controls QML Types}
    for an example. The page is generated from \c {qtquickcontrols2-qmlmodule.qdoc}.
    There you will find a QDoc comment containing the \c{\qmlmodule} command for
    the QtQuick.Controls module. The same comment contains a \c {\noautolist}
    command to disable automatic list generation, and a \l {generatelist-command}
    {\\generatelist} to list the QML types in a specific section of the document.
 
    This command was introduced in QDoc 5.6.
 
    Since Qt 5.10, this command can be applied also to \l{example-command}
    {\\example} documentation, where it causes the automatically generated
    list of files and images belonging to an example project to be omitted.
 
    \target omit-command
    \section1 \\omit
 
    The \\omit command and the corresponding \\endomit command
    delimit parts of the documentation that you want QDoc to skip. For
    example:
 
    \badcode *
    /\1!
        \table
        \row
            \li Basic Widgets
            \li Basic GUI widgets such as buttons, comboboxes
               and scrollbars.
 
        \omit
        \row
            \li Component Model
            \li Interfaces and helper classes for the Qt
               Component Model.
        \endomit
 
        \row
            \li Database Classes
            \li Database related classes, e.g. for SQL databases.
        \endtable
    \1/
    \endcode
 
    \target raw-command
    \section1 \\raw (avoid!)
 
    The \\raw command and the corresponding
    \\endraw command delimit a block of raw mark-up language code.
 
    \warning Avoid using this command if possible. If you are trying to
    generate special table or list behavior, try to get the behavior you want
    using the \l {span-command} {\\span} and \l {div-command} {\\div}
    commands in your \l {table-command} {\\table} or \l {list-command}
    {\\list}.
 
    The command takes an argument specifying the code's format.
 
    QDoc generates the given code only when generating the format that
    was specified by the user.
 
    For example, "\\raw HTML" will only generate code when QDoc
    generates HTML documentation.
 
    \note You can often achieve the intended purpose by using QDoc commands,
    while reducing the chance of mistakes or content becoming unmaintained.
 
    \target sincelist-command
    \section1 \\sincelist
 
    The \\sincelist command expands to a detailed breakdown of new
    inclusions to the documented API in a specified version. Example
    usage:
 
    \badcode * \QtMajorVersion \QtMinorVersion \QtVer
    /\1!
       \page newclasses\2\3.html
       \title New Classes and Functions in \4
       \brief A comprehensive list of new classes and functions in \4.
 
       \sincelist \4
    \1/
    \endcode
 
    \\sincelist takes a single argument, a version string. The generated
    output includes all functionality that is marked with a
    \l {since-command}{\\since} command or a \l {since clause} matching
    the version string.
 
    \target unicode-command
    \section1 \\unicode
 
    The \\unicode command allows you to insert an arbitrary Unicode
    character in the document.
 
    The command takes an argument specifying the character as an
    integer. By default, base 10 is assumed, unless a '0x' or '0'
    prefix is specified (for base 16 and 8, respectively).
*/