Revision control
++ // 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 Troubleshooting 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 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 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 \\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 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).
++
++ 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
++
++ 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 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 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 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 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 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 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 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 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 Cannot tie this documentation to anything
++
++ QDoc found a \beginqdoc ... \endqdoc comment, with no \l{Topic Commands}{topic command}, and
++ could not associate the declaration or definition immediately following the
++ comment with a documented entity. This can happen if there's no declaration
++ or definition following the comment, or if the entity isn't visible to QDoc,
++ such as when the declaration is behind a preprocessor conditional that QDoc
++ doesn't evaluate.
++
++ \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 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 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 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 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 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 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 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 Empty qdoc snippet <tag> in <file>
++
++ The snippet <tag> was found in the \l {snippet-command}{\\snippet} <file>, but it is empty.
++
++ \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 A \e {hidden friend} can be documented using either the
++ class-qualified syntax or the unqualified free function
++ syntax with its return type.
++
++ \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 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 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 \\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 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 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 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 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 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 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 = "π" # 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 Missing comma in \\sa
++
++ The titles listed for a \l {sa-command}{\\sa} command should be separated
++ from one another with commas.
++
++ \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 Missing image: <imagefile>
++
++ The search path to the image is wrong, or the image file does not exist.
++
++ \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 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 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 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 <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 <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 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 \\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 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 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 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 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 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 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 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 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 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 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 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
++
++ \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 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 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 <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 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 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 Unbalanced parentheses in <text>
++
++ Points to a '(' without a corresponding ')', or vice versa.
++
++ \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 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 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 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 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 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 Unexpected \\snippet
++
++ QDoc issues this warning if it is unable to locate the snippet file
++ quoted in a \l {snippet-command}{\\snippet} command.
++
++ \section1 Unknown base <name> for QML type <type>
++
++ The type name declared as the base type for a QML type was not found, or
++ it was not declared with the \qdoccmd{inherits} command.
++
++ \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 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 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 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 Unrecognized markup language
++
++ This warning occurs when a programming language is specified for a \\code
++ command that QDoc does not recognize. For example, this QML code block has
++ been given the invalid "QL" language:
++
++ \code [text] \\endcode
++ \code [QL]
++ Item {
++ id: my_item
++ }
++ \1
++ \endcode
++ */