qdoc-warnings.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page qdoc-warnings.html
    \previouspage Categories of Documentation
 
    \title How to Resolve QDoc Warnings
 
    QDoc may issue warnings when generating your documentation set.
    This section describes what these warnings mean and how to resolve
    them. This document does not describe warnings generated by Clang.
 
    \section1 Can't link to <target>
 
    QDoc issues this warning when one part of the documentation
    (identified in the warning message) tries to refer to another,
    but doesn't correctly specify that other, the target of the link.
    This may arise because the reference to it is mistyped or because
    the target has changed name (for a function or type) or title
    (for another section).
 
    Search the source code for that particular link target.  If you get no
    results, gradually make the search less specific until you find a match.
 
    If the link target looks like the name of a type or function,
    this could also be due to:
 
    \list
    \li The name (or, for functions, where specified, signature) used
        where it is documented not matching the name used in its
        declaration.
    \li The link target being marked as \l {internal-command}{\\internal} when the linking
        text was not.
    \endlist
 
    \section1 Found a \\target command outside table item in a table
 
    If QDoc encounters a \l {target-command}{\\target command} that is not
    preceded by an \\li command within a \l {table-command}
    {\\table ... \\endtable block}, it issues this warning. The warning is
    followed by the text
    \e {Move the \\target inside the \\li to resolve this warning}.
 
    \section1 Cannot find snippets file to quote from
 
    QDoc issues this warning if it is unable to find the file named
    after a \l {snippet-command}{\\snippet} or \l {quotefromfile-command}{\\quotefromfile} command.
 
    Some useful steps for correcting this:
 
    \list
    \li Check if the snippet file name is correct. QDoc appends the
        snippet file name to each of the directories given in the
        search path, to get a path-name for a candidate file to look
        for. It produces this error when none of these candidates exist.
    \li Check the search path for snippets, given by the \c exampledirs
        configuration variable in the \c{*.qdocconf} file. You may need
        to add an entry to this path, or correct an existing entry.
    \li Check if the snippet file exists, or if it has been moved, renamed
        or removed, which may happen when there are changes to the source
        code that QDoc tries to quote from.
    \endlist
 
    \section1 Unexpected \\snippet
 
    QDoc issues this warning if it is unable to locate the snippet file
    quoted in a \l {snippet-command}{\\snippet} command.
 
    \section1 Undocumented QML <module> referred by <type> or its members
 
    QDoc issues this warning if it is unable to locate a QML module
    based on the identifier passed to the
    \l {inqmlmodule-command}{\\inqmlmodule} or \l {qmlproperty-command}
    {\\qmlproperty} commands associated with a QML \e type.
 
    This means that either documentation for the \l {qmlmodule-command}
    {\\qmlmodule} is missing, or an incorrect module identifier was
    used in \\qmlproperty, \\qmlmethod, or \\qmlsignal command(s).
 
    \section1 No such <type> in QML <module>
 
    QDoc issues this warning if a \l {qmlproperty-command} {\\qmlproperty},
    \l {qmlmethod-command} {\\qmlmethod}, or  \l {qmlsignal-command}
    {\\qmlsignal} command argument uses a QML module identifier, but
    the associated \l {qmltype-command}{\\qmltype} does not belong to
    that module.
 
    The QML module identifier, if defined, \b must match with the
    \l {inqmlmodule-command} {\\inqmlmodule} argument in the QML type
    documentation. In most cases, QDoc is able to locate the QML type
    without a module identifier.
 
    \section1 Undocumented return value
 
    For functions whose return-type is not void, QDoc checks if the return
    value is documented. This warning is issued if the documentation for a
    function or method doesn't contain a word starting with "return".
 
    \section1 Undocumented parameter
 
    QDoc requires the documentation of a function or method to describe
    every parameter.  It recognizes this by each parameter name (as
    specified where the function or method is declared in a header file)
    appearing after a \l {a-command}{\\a} command.
 
    This requirement is not imposed for function overload documentation,
    provided that the overload is marked with the \qdoccmd overload command
    and a fully-documented function with the same name exists.
 
    \section1 No such parameter
 
    QDoc issues this warning when the parameter name given after an
    \l{a-command}{\\a} command does not match any of the parameters named
    in the header-file's declaration of the function or method being
    documented.
 
    \section1 Unknown macro
 
    QDoc issues this warning when it sees a backslash, \c{\}, followed
    by a token it doesn't recognize as the name of either a built-in command
    or a \l {macro-variable}{user-defined macro}. When quoting code
    that contains character escape sequences, you should enclose the
    code in \\c{...} to prevent this warning against the escape sequences.
 
    \section1 Failed to find function when parsing \\fn <signature>
 
    When Clang parses a function signature following an \qdoccmd fn command,
    it checks this against the declaration in the header file. If Clang
    discovers discrepancies, it issues this warning message.
 
    The signature must be fully qualified. Typical issues include missing or
    incorrect template arguments, return type, or qualifiers such as
    \e const.
 
    \note The \c{\fn} signature for a \e {hidden friend} should be
          fully qualified with the scope of the class that declares
          the function.
 
    \section1 No output generated for <entity> because <parent> is undocumented
 
    QDoc issues this warning when parsing a documentation comment for an
    API entity such as a class member, but cannot produce any output because
    the associated parent (class) is not documented. Ensure that the parent is
    documented and that QDoc is configured to parse the source file containing
    the documentation comment.
 
    If the documented member belongs to a class that is not meant to be
    documented, mark the class as \qdoccmd {internal} or use the
    \qdoccmd {dontdocument} command.
 
    \section1 QML type <TypeName> documented with <ClassName> as its native type. Replacing <ClassName> with <OtherClass>
    If the \qdoccmd nativetype command is used with the same argument in
    multiple QML type documentation comments that belong to the same
    documentation project, QDoc issues this warning. To resolve this, ensure
    that you use the \c {\nativetype} command only once for each C++ class.
 
 
    \section1 Cannot tie this documentation to anything
 
    QDoc found a \beginqdoc ... \endqdoc comment, with no \l{Topic Commands}{topic command}, that was
    not immediately followed by a class, function or property definition.
    It thus does not know what the comment documents.
 
    \section1 This qdoc comment contains no topic command (e.g., \\module, \\page)
 
    If a QDoc comment doesn't contain a \l {Topic Commands}{topic command}, QDoc does
    not know what the comment documents, and issues this warning.
    Very similar to \l {Cannot tie this documentation to anything}, but
    specific to comments that are not in C++ or QML files.
 
    \section1 <name> documented more than once
 
    QDoc issues this warning when it finds two comments that
    document the same item. The location of the previously seen
    comment is provided in warning details.
 
    For example, you see this warning when a function has a documentation
    comment preceding its definition, and a separate \\fn comment
    elsewhere.
 
    \section1 <topic> cannot be mixed with other topic commands
 
    QDoc allows multiple topic commands in a single documentation
    comment for certain \l{Writing Documentation#Multiple topics}{use cases}.
    Using multiple topic commands from different categories prints
    out this warning, and the topic generates no output.
 
    \section1 Namespace <name> documented more than once
 
    This warning means that a documentation set contains two comments
    containing \l {namespace-command}{\\namespace} commands with the same
    argument, <name>.
 
    \section1 <name> is documented, but namespace <namespace> is not documented in any module
 
    The documentation for \e {<name>} was found, but \e{<name>} is declared
    under a namespace that is either undocumented or QDoc was unable to
    locate the documentation for it.
 
    This can be resolved by either documenting \e{<namespace>}, or if it is
    already documented in another module, ensure that this module has
    a dependency to it.
 
    See also \l {depends-variable}{depends} and \l {indexes-variable}{indexes}.
 
    \section1 Has no \\inmodule command
 
    QDoc issues this warning if the QDoc comments do not relate
    a class, namespace, or headerfile to a module with the
    \l{inmodule-command}{\\inmodule} command.
 
    If the QDoc comment describes an entity that's not a member of
    some other entity (typically a namespace or class), it should use
    either \l {relates-command}{\\relates} or \l {inmodule-command}{\\inmodule}
    to associate it with its broader context. This warning is raised
    if it does not.
 
    \section1 Cannot find <name> specified with \<command> in any header file
 
    This means that QDoc cannot find a declaration of <name> in any
    header file, but has found a comment that claims to document it.
 
    An example:
    \badcode
    Cannot find 'Color::Red' specified with '\enum' in any header file.
    \endcode
 
    A documentation comment claims to describe an enum, but QDoc didn't
    find a definition of that enum in a header file.
 
    This may also be due to:
 
    \list
        \li a typo in <name> or <command>
        \li a missing namespace-or-class prefix
        \li <name> having moved to another namespace or class
    \endlist
 
    \section1 Unrecognizable QML module/type qualifier for <identifier>
 
    A parameter passed to \l {qmlproperty-command}{\\qmlproperty} or
    \l {qmlmethod-command}{\\qmlmethod} contains a combination of
    qmlModule::qmlType::identifier that is not defined anywhere.
 
    Example:
    \badcode
    Unrecognizable QML module/type qualifier for real QtQuick::DragHandler::DragAxis::minimum
    \endcode
 
    DragHandler doesn't have a property called DragAxis.
 
    \section1 Missing property type for <name>
 
    A declaration of a \l {qmlproperty-command}{\\qmlproperty} is missing its property type.
 
    The \\qmlproperty command expects to be followed by the property type, then the
    fully-qualified name of the property (i.e. the name ::-joined after the name of the
    class it belongs to).
 
    Incorrect:
      \badcode
      \qmlproperty MyWidget::count
      \endcode
 
    Correct:
      \badcode
      \qmlproperty int MyWidget::count
      \endcode
 
    \section1 Undocumented property '<name>'
 
    This warning indicates that a C++ class has a Q_PROPERTY declaration that lacks
    documentation. Properties are part of a class's public API and require
    documentation using the \c \property command to describe their purpose,
    valid values, and behavior.
 
    \note If you see both "Cannot find '<ClassName::propertyName>' specified with
    '\\property'" and "Undocumented property '<ClassName::propertyName>'" warnings
    together, the \c \property command exists but cannot match the property in code.
    Dual warnings indicate mismatched property documentation: the \c \property command
    can't find its target, and the PropertyNode has no attached documentation. Check
    that the fully qualified name matches exactly, including namespace and class scope.
 
    \section1 QML property documented multiple times: <identifier>
 
    QDoc uses this warning when it finds two QDoc comments that document
    the same QML property, either by appearing just before its definition,
    or using the \l {qmlproperty-command}{\\qmlproperty} command.
 
    \section1 Command <command> not allowed with QML property commands
 
    Example:
 
    \badcode
    \qmlproperty real QtQuick.Controls::RangeSlider::first.value
    \qmlproperty real QtQuick.Controls::RangeSlider::first.position
    \qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
    \qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
    \qmlsignal void QtQuick.Controls::RangeSlider::second.moved()
    \endcode
 
    Error message:
 
    \badcode
    Command '\\qmlsignal' not allowed with QML property commands
    \endcode
 
    This warning is specific to property group documentation.  QDoc
    allows multiple qmlproperty or qmlattachedproperty topic commands
    in a single documentation comment to document a property group
    where the last element in the path is <group>.<property>. Any other topic
    commands triggers this warning.
 
    \section1 Cannot find base function for <method> in <class>
 
    QDoc produces this warning if \\reimp is used to document a method,
    as an override of a virtual method, when no base class has a virtual
    method with the given name and signature. This may happen because
    the method it was written to override has changed its signature, or is
    no longer virtual.
 
    \section1 Illegal \\reimp; no documented virtual function for <command>
 
    Qdoc tries to create a  link to the function that this one reimplements,
    but it could not find the link target, likely because that
    function is not documented. This can also arise if no base class
    has a virtual method with this name and signature; which might
    arise due to a renaming, a change in signature or the base no
    longer declaring it virtual.
 
    \section1 Multiple primary overload definitions for <function>
 
    QDoc issues this warning when multiple functions with the same name are
    marked with \c{\overload primary}. Only one function in an overload
    group should be designated as the primary overload.
 
    The warning includes the function signatures and their source locations
    to help identify all competing primary overloads. QDoc will determine
    the actual primary overload using lexicographic comparison (alphabetical
    ordering of function signatures) among the functions marked as primary.
 
    To resolve this warning, remove the \c{primary} argument from all but
    one of the \c{\overload primary} commands in the overload group.
 
    Example that triggers this warning:
 
    \badcode *
    /\1!
        \overload primary
        Does something with no parameters.
    \1/
    void doSomething();
 
    /\1!
        \overload primary
        Does something with a parameter.
    \1/
    void doSomething(int value);
    \endcode
 
    Correct approach - only one primary:
 
    \badcode *
    /\1!
        \overload primary
        Does something with no parameters.
    \1/
    void doSomething();
 
    /\1!
        \overload doSomething()
        Does something with a parameter.
    \1/
    void doSomething(int value);
    \endcode
 
    \section1 <class> tries to inherit itself
 
    The \l {inherits-command}{\\inherits} command is used to document that a QMl type
    inherits some other QML type. This warning is issued if that other
    QML type is the same as the QML type documented.
 
    Example:
 
    \badcode
        \qmltype Foo
        \inherits Foo
    \endcode
 
    \section1 \\nativetype is only allowed in \\qmltype
 
    The \l{nativetype-command}{\\nativetype} command can only be used in a QDoc
    comment that documents a QML type.
 
    \section1 All properties in a group must belong to the same type: <name>
 
    When documenting QML property groups, all properties listed in
    the comment block must belong to the same QML type.
 
    \section1 Cannot find project file for example <name>
 
    In the example's source directory, QDoc expects to find a project
    file named \c{CMakeLists.txt}, or a file with a \c{.pro}, \c{.qmlproject}, or
    \c{.pyproject} extension where the base name matches that of the example
    directory. For example, \c {examples/mymodule/helloworld/helloworld.pro}.
 
    \section1 Cannot open file to quote from: <filename>
 
    The search path for <filename> is defined by the following
    variables in the \c{.qdocconf} file:  \c{sources}, \c{sourcedirs},
    and \c{exampledirs}.
 
    QDoc failed to find a file named in a command (such as
    \l {quotefromfile-command}{\\quotefromfile},
    \l {snippet-command}{\\snippet}, \l {include-command}{\\include})
    that tells it to retrieve content from the named file. It searches
    each directory named in the search path.  If there is no file with
    this name in any of those directories, or the file is found but not
    readable, QDoc issues this warning. Check that the combination of
    search path and <filename> is correctly spelled, and that you have
    read permissions for the file.
 
    \note <filename> may include a directory name prefix; the whole
          <filename> is appended to each directory in the search path.
 
    \sa {Cannot find qdoc include file <filename>}
 
    \section1 Missing format name after \\raw
 
    The \l {raw-command}{\\raw} command and the corresponding \l {raw-command}{\\endraw}
    command delimit a block of raw mark-up language code. The \\raw
    command must be followed by the format name.
 
    \section1 Macro cannot have both format-specific and qdoc-syntax definitions
 
    A \l {macro-variable}{\\macro} that specifies an output format cannot also
    have a generic definition.
 
    An example of a configuration that triggers this warning:
 
    \badcode
    macro.gui = \b
    macro.gui.HTML = "<b>\1</b>"
    \endcode
 
    \section1 Unknown command <name>
 
    When a QDoc comment uses a backslash followed by a token that is not a QDoc
    built-in command and has not been defined as a custom command
    \l {macro-variable}{macro}, QDoc produces this warning. Check the spelling
    of the command name, and check whether your QDoc configuration doesn't
    include whatever would have defined it, if it's a custom command.
 
    This may also be produced due to code being quoted in the QDoc comment,
    for example the author may have referred to the C string termination
    character \c{'\0'} or one of the other C string escape sequences such
    as \c{'\n'} without escaping the backslash. Escape the backslash
    as \c{\} to include a literal backslash in the documentation, or
    enclose the code fragment in \c{\c{...}}, which suppresses
    interpretation of backslashes as introducing QDoc commands.
 
    \section1 Duplicate target name <target>
 
    This warning is issued if you define two targets with the same parameter,
    using either the \l {target-command}{\\target} or the \l {keyword-command}
    {\\keyword} command. The target name given as parameter to these commands
    must be unique. The warning is followed by "The previous occurrence is
    here: [location]", where location contains a file name and line number.
 
    \section1 Cannot find qdoc include file <filename>
 
    QDoc failed to find an include file named in a command.
    QDoc searches each directory named in the search path.
    If there is no file with this name in any of those directories,
    or the file found in that search is not readable, QDoc issues
    this warning. Check that the combination of search path and
    <filename> is correctly spelled, and that you have read permissions
    for the file.
 
    \note <filename> may include a directory name prefix; the whole
          <filename> is appended to each directory in the search path.
 
    \sa {Cannot open file to quote from: <filename>}
 
    \section1 Cannot find <tag> in <file>
 
    This means QDoc cannot find the identifier <id> in the
    \l{include-command}{\\include} <file> or {snippet-command}{\\snippet} <file>.
 
    \section1 Empty qdoc snippet <tag> in <file>
 
    The snippet  <tag> was found in the \l {snippet-command}{\\snippet} <file>, but it is empty.
 
    \section1 Cannot nest <command> commands
 
    This warning concerns formatting commands: bold, italic,
    index, link, span, subscript, superscript, teletype, uicontrol,
    underline. A formatting command cannot be used within the text
    it applies to. An example of this:
 
    \badcode
    There is \b{no \b{super-}bold}.
    \encode
 
    \section1 Can't use <inner> in <outer>
 
    This warning is issued for commands that cannot be nested.
 
    Example:
    \badcode
        \list
            \li \table
                \row \li Hello \li Hi
                \endtable
        \endlist
    \endcode
 
    Results in the QDoc warning "Can't use '\\table' in '\\list'".
 
    \section1 Missing <outer> before <inner>
 
    Some examples:
 
    \list
    \li The \l {li-command}{\\li} command can only be used inside a \l {list-command}{\\list}
        or a \l {row-command}{\\row} of a \l {table-command}{\\table}.
    \li The \l {row-command}{\\row} and \l {header-command}{\\header} commands can only be
        used within a \l {table-command}{\\table}.
    \endlist
 
    \section1 Unexpected <end_command>
 
    This warning is issued if, for example, you have an \l {list-command}{\\endlist} without
    a preceding \l {list-command}{\\list}. It applies to all commands that come in pairs (e.g.
    startFoo/endFoo).
 
    \section1 Missing comma in \\sa
 
    The titles listed for a \l {sa-command}{\\sa} command should be separated
    from one another with commas.
 
    \section1 Macro <command> does not have a default definition
 
    QDoc is attempting to expand a macro, and expects that macro to
    have a default definition. Some macros may only have format-specific
    definitions.
 
    Example:
    \badcode
    macro.pi.HTML = "&pi;"    # encodes the pi symbol for HTML output format
    \endcode
 
    There are however instances where macro expansion requires a
    format-independent macro. For example, you can have macros in
    section titles, but they must have default definitions.
 
    \section1 Macro <macro> invoked with too few arguments (expected <many>, got <few>)
 
    The given macro needs more parameters than it was given.  See
    the definition of the macro in the configuration for further
    details.
 
    \section1 Unbalanced parentheses in <text>
 
    Points to a '(' without a corresponding ')', or vice versa.
 
    \section1 No documentation for <name>
 
    Example:
 
    \badcode
    Warning "No documentation for QNativeInterface."
    \endcode
 
    QDoc detects the declaration of namespace QNativeInterface in
    a header file, but does not find a QDoc comment where that
    namespace has been documented.
 
    \section1 No such enum item <name> in <class>
 
    Example:
 
    \badcode
    Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
    with \enum in any header file.
    \endcode
 
    QDoc issues this warning when it finds a \l{value-command}{\\value} directive in an
    \l{enum-command}{\\enum} comment that names a value not found in the header file that declared
    the enumerated type documented.
 
    \section1 Undocumented enum item <enum> in <enum list>
 
    <enum list>'s \l {value-command}{\\value} or \l {omitvalue-command}{\\omitvalue} entries
    did not include one for \l {enum-command}{<enum>}, which is named in the
    declaration of <enum list> in the header file.
 
    \section1 Failed to find qhp.<project>.subprojects.<subproject>.indexTitle
 
    QDoc failed to find a title for a page designated as the index page
    for <subproject> in the Qt help project configuration.
 
    Subproject index titles must be local to the current documentation project.
    Using a page title from another project, loaded as a dependency, also
    results in this warning.
 
    For more information, see \l {Creating Help Project Files}.
 
    \section1 \\generatelist <group> is empty
 
    Below a short overview of all possible arguments for \l {generatelist-command}{\\generatelist}:
    \list
    \li \\generatelist annotatedexamples
    \li \\generatelist annotatedattributions
    \li \\generatelist classes <prefix>
    \li \\generatelist classesbymodule <module name>
    \li \\generatelist qmltypesbymodule <module name>
    \li \\generatelist functionindex
    \li \\generatelist legalese
    \li \\generatelist overviews
    \li \\generatelist attributions
    \li \\generatelist related
    \endlist
 
    QDoc issues this warning if you specify \c{\generatelist <group>}
    and the group does not contain any items, or if you specify
    \c{\generatelist <group> <pattern>} and no item in the group
    matches the pattern.
 
    \section1 \\generatelist <group> no such group
 
    This warning issues if the argument to \l {generatelist-command}{\\generatelist}
    is a non-existing group.
 
    Example:
 
    \code
    \generatelist draganddrop
    \endcode
 
    This statement generates a list of classes or QML types in the
    draganddrop group.  Classes or QML types are added to the
    draganddrop group by the \c{\l {ingroup-command}{\ingroup} draganddrop} command in their
    \l {class-command}{\\class} or \l {qmltype-command}{\\qmltype} comment.
 
    QDoc issues this warning message if no entity has
    this \c{\ingroup draganddrop} statement.
 
    \section1 Missing image: <imagefile>
 
    The search path to the image is wrong, or the image file does not exist.
 
    \section1 Can't link to <target>
 
    This can have a variety of causes:
 
    \list
       \li The link target has not been defined with a QDoc topic command,
           e.g. {title-command}{\\title} <target>.
       \li The <target> contains a typo.
       \li The document that contains that link target did not get compiled.
       \li The document that contains that link target is in a module that is
           not in the compilation path.
       \li The link target is in another module, and a dependency to that
           module was not set in the configuration or QDoc failed to locate
           the index file for the dependency.
    \endlist
 
    \section1 Could not resolve QML import statement for type <name>
 
    QDoc issues this warning if you document a QML type, but omit
    the \l{inqmlmodule-command}{\\inqmlmodule} command.
    Example:
 
    \badcode
    Could not resolve QML import statement for type 'ItemSelectionModel'
    \encode
 
    Incorrect:
      \badcode
      \qmltype ItemSelectionModel
      \nativetype QItemSelectionModel
      \since 5.5
      \ingroup qtquick-models
      \endcode
    Correct:
      \badcode
      \qmltype ItemSelectionModel
      \nativetype QItemSelectionModel
      \inqmlmodule QtQml.Models
      \since 5.5
      \ingroup qtquick-models
      \endcode
 
    \section1 \\brief statement does not end with a full stop
 
    The argument to the \\brief command is a sentence, summarizing
    the topic documented, so should end in a full stop. It should
    also be brief.
 
    \section1 QtDeclarative not installed; cannot parse QML
 
    QDoc issues this warning if it has been compiled without support
    for QML parsing. This should not happen unless you have a
    custom build of QDoc.
 
    \section1 Invalid regular expression <regex>
 
    Some QDoc commands take regular expressions as parameters. QDoc
    gives this warning when the text given as such a parameter is not
    a valid regular expression, usually due to it containing characters
    with special meanings in regular expressions, that should have been
    escaped.
 
    Example:
 
    \badcode
    notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'
    \endcode
 
      \badcode
      \quotefromfile webenginewidgets/notifications/data/index.html
      \skipuntil resetPermission
      \endcode
 
    Invalid regular expression:
      \badcode
      \printuntil /^})$/
      \endcode
 
    Valid regular expression:
      \badcode
      \printuntil /^\}\‍)$/
      \endcode
 
 
    The \l {printuntil-command}{\\printuntil} command prints until it
    meets a line consisting of only a right curly brace followed by a
    right parenthesis. In this case, the curly brace and the parenthesis
    need to be escaped because they have special meanings in regular
    expressions.
 
    \section1 Multiple index files found for dependency <indexfile>:<depend>
              Using <indexfile> as index file for dependency <depend>
 
    Multiple \c{-indexdir} paths were passed to QDoc as command line options,
    and more than one contained an \c{.index} file that matches a dependency.
    QDoc picks the one with the latest timestamp automatically.
 
    Typically, this warning indicates that there are build artifacts left
    from a previous documentation build.
 
    \section1 Cannot locate index file for dependency <depend>
 
    Example:
 
    \badcode
    "QMake" Cannot locate index file for dependency "activeqt"
    \endcode
 
    The documentation project QMake could not locate activeqt.index
    in any of the specified index directories. In this case, the
    specified index directories are specified in qmake.qdocconf.
 
    \section1 Dependent modules specified, but no index directories were set.
 
    QDoc expected to see one or more -indexdir arguments on the command line.
    Without them, QDoc cannot locate the index files of any dependencies
    defined with the 'depends' configuration variable.
 
    \section1 Overrides a previous doc
 
    QDoc issues this warning when it finds two comments that appear to
    describe the same entity. The location of the previously seen
    comment is provided in warning details.
 
    \section1 Unrecognized list style <name>
 
    \\list can take an optional argument: a single number or character
    that modifies the list style. Refer to the {list-command}{\\list}
    documentation for more details. If you use an argument that is
    not recognized, QDoc issues this warning.
 
    \section1 Unable to parse QML snippet: <code> at line <y>, column <x>
 
    QDoc comments can contain QML code. This code can be found in a snippet,
    or in the QDoc comments delimited by \l {qml-command}{\\qml} and {endqml-command}{\\endqml}.
 
    Example:
 
    If there is a syntax error in the QML code, QDoc issues the warning
    \badcode
    Unable to parse QML snippet: Syntax error at line 97, column 42
    \endcode
 
    Snippets can also contain QML and also there the code is checked. If there is
    for example a missing curly brace in the code, QDoc issues the warning
    \badcode
    Unable to parse QML snippet: Expected token '{' at line 63, column 52
    \endcode
 
    QDoc often fails to parse incomplete QML snippets; in these cases,
    it's often OK to replace the \\qml ... \\endqml commands with
    \\code ... \\endcode to suppress this warning.
 
    \section1 Command <command> failed at end of file <filename>
 
    Example:
 
    \badcode
    Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".
    \endcode
 
    In this case the warning means that the \l {snippet-command}{\\snippet} command did not find a second
    label "\/\/! [2]" to mark the end of the snippet. It could also mean that it didn't
    find any occurrence of that snippet tag in this snippet file.
 
    Another example:
 
    \badcode
    Command '\skipto' failed at end of file 'styling/CMakeLists.txt".
    \endcode
 
    The \l {skipto-command}{\\skipto} + <pattern> moves the cursor to the next line containing
    that pattern. If \\skipto doesn't find it, QDoc issues this warning.
 
    \section1 Failed to open <file> for writing
 
    This warning clearly means it cannot open a file for writing, probably because
    of a wrong path, or permission to write in a certain directory.
 
    \section1 This page title exists in more than one file
 
    The \l {title-command}{\\title} command sets the title for a page.
 
    \code
        \page activeqt-server.html
        \title Building ActiveX servers in Qt
    \endcode
 
    QDoc issues this warning if a certain title is used in more than one page.
 
 
    \section1 The content is too long
 
    QDoc uses a fixed-size buffer when tokenizing source files. If any single
    token in the file has more characters than the maximum limit, QDoc issues
    this warning.
 
    While QDoc continues parsing the file, only the part of the token that
    fits into the buffer is considered, meaning that the output might be
    mangled.
 
    To resolve this warning, the relevant content must be reduced in size,
    either by splitting it, if possible, or by removing some of its parts.
 
    The maximum amount of characters for a single token is shown alongside
    the warning, for example:
 
    \badcode
        file.qdoc:71154: (qdoc) warning: The content is too long.
 
        [The maximum amount of characters for this content is 524288.
        Consider splitting it or reducing its size.]
    \endcode
 
    \note Since content that is too long is not parsed in full, QDoc may
    issue warnings that are false positives. Resolve all warnings of this type
    before fixing other warnings.
 
    \section1 No documentation generated for function <name> in global scope
 
    QDoc was able to match the documentation for a function \e {<name>} to its
    declaration, but no output was generated because the function is declared
    in the global namespace.
 
    Use the \l {relates-command}{\\relates} command to associate the function
    with a documented type, namespace, or a header file. The function is then
    listed as a \e {related non-member} on the associated reference page.
 
    \section1 Documentation configuration for <project> doesn't define a help project (qhp)
 
    A valid Qt help configuration was expected but not provided in the project's
    .qdocconf file.
 
    See also \l{Creating Help Project Files} and \l {qhp-variable}{qhp}.
 
    \section1 Already generated FILE for this project
 
    While generating the documentation for a project, QDoc keeps track of the
    file names of the files it has generated. QDoc will issue a warning when it
    opens a file for writing if that file is known to have been generated
    previously, in the current execution. This can happen if a \qdoccmd page
    command uses the same name as \qdoccmd group, for example.
 
    You can set the environment variable \c QDOC_ALL_OVERWRITES_ARE_WARNINGS to
    unconditionally warn about all such events. This may be useful when tracking
    down the offending definitions.
 
    \section1 Invalid QML property type
 
    The type used to declare a QML property was not a valid
    \l{QML Value Types}{QML value type} or \l{QML Object Types}{QML object type},
    or it was a C++ or Qt type.
 
    This warning typically occurs when developers refer to the underlying Qt
    type used to implement a QML type, such as QStringList instead of
    \c{list<string>}.
 
    \section1 Type is its own base type: <type>
 
    The QML type has been incorrectly defined as its own base type, possibly
    using the \l {inherits-command}{\\inherits} command.
 
    \section1 Cyclic type inheritance: <type>
 
    Cyclic or circular inheritance occurs when a QML type inherits from a base
    type that itself inherits from the original type. This can occur between
    two mutually inheriting types, or there may be intermediate types between
    them.
 
    This warning indicates where a cycle in the inheritance hierarchy has been
    detected. You should examine the \l {inherits-command}{\\inherits} command
    for the type and follow the trail of base types until one is found that
    inherits from a type that you have previously encountered. You should then
    break the cycle by fixing the incorrect \l {inherits-command}{\\inherits}
    command for one of the identified types.
 
    \section1 Redundant link to self in \\sa command for <name>
 
    A piece of documentation contains a link to itself in the references defined
    in its \l {sa-command}{\\sa} command.
 
    This problem tends to occur when there is a collection of related properties
    or methods that refer to each other, and where the \\sa commands have been
    copied between them, as in this example:
 
    \badcode
        \fn void Items::append(const Item &)
        ...
        \sa append(), count(), insert(), remove()
    \endcode
 
    It is useful to replace the self-referencing link with one to another
    related property or method.
 
    Alternatively, the link may not be specific enough for QDoc to resolve, as
    in this example:
 
    \badcode
        \fn void MyPicture::setSize(int)
        ...
        \sa setSize()
    \endcode
 
    In this case, the intention may have been to refer to an overload that
    accepts a \c double argument:
 
    \badcode
        \fn void MyPicture::setSize(int)
        ...
        \sa setSize(double)
    \endcode
*/