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.

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:

• The name (or, for functions, where specified, signature) used where it is documented not matching the name used in its declaration.
• The link target being marked as \internal when the linking text was not.

Cannot find snippets file to quote from

QDoc issues this warning if it is unable to find the file named after a \snippet or \quotefromfile command.

Some useful steps for correcting this:

• 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.
• Check the search path for snippets, given by the exampledirs configuration variable in the *.qdocconf file. You may need to add an entry to this path, or correct an existing entry.
• 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.

Unexpected \snippet

QDoc issues this warning if it is unable to locate the snippet file quoted in a \snippet command.

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".

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 \a command.

No such parameter

QDoc issues this warning when the parameter name given after an \a command does not match any of the parameters named in the header-file's declaration of the function or method being documented.

Unknown macro

QDoc issues this warning when it sees a backslash, \, followed by a token it does not recognize as the name of a built-in command or a 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.

Clang couldn't find function when parsing \fn <signature>

When Clang parses a function statement after \fn, it checks this against the declaration in the header file. If Clang discovers discrepancies, it issues this warning message.

C++ class <ClassName> not found: \instantiates <ClassName>

If you describe a QML type, you may specify the class it instantiates. Refer to the \instantiates command in the QDoc manual.

QDoc issues this warning if it failed to locate the documentation for the C++ class <ClassName>. Either the class is undocumented, it is marked \internal, or it originates from another documentation module and QDoc did not locate an index file for the corresponding dependency.

See also depends.

Cannot tie this documentation to anything

QDoc found a /*! ... */ comment, with no topic command, that was not immediately followed by a class, function or property definition. It thus does not know what the comment documents.

This qdoc comment contains no topic command (e.g., \module, \page)

If a QDoc comment doesn't contain a topic command, QDoc does not know what the comment documents, and issues this warning. Very similar to Cannot tie this documentation to anything, but specific to comments that are not in C++ or QML files.

<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.

Namespace <name> documented more than once

This warning means that a documentation set contains two comments containing \namespace commands with the same argument, <name>.

<name> is documented, but namespace <namespace> is not documented in any module

The documentation for <name> was found, but <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 <namespace>, or if it is already documented in another module, ensure that this module has a dependency to it.

See also depends and {indexes-variable}{indexes}.

Clang couldn't find function when parsing \fn <signature>

When parsing a \fn statement, Clang compares this with the function declaration in the header file. If the signature differs Clang issues this warning.

• A member of a class or namespace needs to include the class or namespace prefix on the member name.
• A \fn with no return type matches, regardless of the actual return type, but if it specifies an incorrect return type, it doesn't.
• Differences in \fn's parameter names don't preclude matching, although the \a commands in the comment must use the names in the declaration.

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 \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 \relates or \inmodule to associate it with its broader context. This warning is raised if it does not.

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:

Cannot find 'Color::Red' specified with '\enum' in any header file.

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:

• a typo in <name> or <command>
• a missing namespace-or-class prefix
• <name> having moved to another namespace or class

Unrecognizable QML module/component qualifier for <identifier>

A parameter passed to \qmlproperty or \qmlmethod contains a combination of qmlModule::qmlType::identifier that is not defined anywhere.

Example:

Unrecognizable QML module/component qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler doesn't have a property called DragAxis.

Missing property type for <name>

A declaration of a \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:

\qmlproperty MyWidget::count

Correct:

\qmlproperty int MyWidget::count

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 \qmlproperty command.

Command <command> not allowed with QML property commands

Example:

\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()

Error message:

Command '\\qmlsignal' not allowed with QML property commands

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.

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.

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.

<class> tries to inherit itself

The \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:

\qmltype Foo
\inherits Foo

\instantiates is only allowed in \qmltype

The \instantiates command can only be used in a QDoc comment that documents a QML type.

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.

Cannot find project file for example <name>

In the example's source directory, QDoc expects to find a project file named CMakeLists.txt, or a file with a .pro, .qmlproject, or .pyproject extension where the base name matches that of the example directory. For example, examples/mymodule/helloworld/helloworld.pro.

Command name <alias> cannot stand for both <first> and <later>

QDoc issues this warning when one name is aliased to more than one command when reading the configuration.

Cannot open file to quote from: <filename>

The search path for <filename> is defined by the following variables in the .qdocconf file: sources, sourcedirs, and exampledirs.

QDoc failed to find a file named in a command (such as \quotefromfile, \snippet, \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.

Missing format name after \raw

The \raw command and the corresponding \endraw command delimit a block of raw mark-up language code. The \raw command must be followed by the format name. For now, this can only be HTML.

Macro cannot have both format-specific and qdoc-syntax definitions

A \macro that specifies an output format cannot also have a generic definition.

An example of a configuration that triggers this warning:

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

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 using \alias or macro, QDoc produces this warning. Check the spelling of the command name and look to see if your QDoc configuration has neglected to include whatever would have defined it, if it is 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 '\0' or one of the other C string escape sequences such as '\n' without escaping the backslash. Escape the backslash as \ to include a literal backslash in the documentation, or enclose the code fragment in \c{...}, which suppresses interpretation of backslashes as introducing QDoc commands.

Duplicate target name <target>

This means that there are two \target commands with the same parameter. They should be unique. This warning is followed by the warning "The previous occurrence is here".

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.

Cannot find <tag> in <file>

This means QDoc cannot find the identifier <id> in the \include <file> or {snippet-command}{\snippet} <file>.

Empty qdoc snippet <tag> in <file>

The snippet <tag> was found in the \snippet <file>, but it is empty.

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:

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

Results in the QDoc warning "Can't use '\table' in '\list'".

Missing <outer> before <inner>

Some examples:

• The \li command can only be used inside a \list or a \row of a \table.
• The \row and \header commands can only be used within a \table.

Unexpected <end_command>

This warning is issued if, for example, you have an \endlist without a preceding \list. It applies to all commands that come in pairs (e.g. startFoo/endFoo).

Missing comma in \sa

The titles listed for a \sa command should be separated from one another with commas.

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:

macro.pi.HTML = "π"    # encodes the pi symbol for HTML output format

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.

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.

Unbalanced parentheses in <text>

Points to a '(' without a corresponding ')', or vice versa.

No documentation for <name>

Example:

Warning "No documentation for QNativeInterface."

QDoc detects the declaration of namespace QNativeInterface in a header file, but does not find a QDoc comment where that namespace has been documented.

No such enum item <name> in <class>

Example:

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

QDoc issues this warning when it finds a \value directive in an \enum comment that names a value not found in the header file that declared the enumerated type documented.

Undocumented enum item <enum> in <enum list>

<enum list>'s \value or \omitvalue entries did not include one for <enum>, which is named in the declaration of <enum list> in the header file.

Failed to find index: <filename>

Example:

Failed to find index: path/to/QtCrator/appmanplugin/manual.index

In this case, it clearly means the indexes variable contains a typo in the path of the index file.

Incorrect:

indexes += path/to/QtCrator/appmanplugin/manual.index

Correct:

indexes += path/to/QtCreator/appmanplugin/manual.index

\generatelist <group> is empty

Below a short overview of all possible arguments for \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist classes <prefix>
• \generatelist classesbymodule <module name>
• \generatelist qmltypesbymodule <module name>
• \generatelist functionindex
• \generatelist legalese
• \generatelist overviews
• \generatelist attributions
• \generatelist related

QDoc issues this warning if you specify \generatelist <group> and the group does not contain any items, or if you specify \generatelist <group> <pattern> and no item in the group matches the pattern.

\generatelist <group> no such group

This warning issues if the argument to \generatelist is a non-existing group.

Example:

\generatelist draganddrop

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 \l {ingroup-command}{\ingroup} draganddrop command in their \class or \qmltype comment.

QDoc issues this warning message if no entity has this \ingroup draganddrop statement.

Missing image: <imagefile>

The search path to the image is wrong, or the image file does not exist.

Can't link to <target>

This can have a variety of causes:

• The link target has not been defined with a QDoc topic command, e.g. {title-command}{\title} <target>.
• The <target> contains a typo.
• The document that contains that link target did not get compiled.
• The document that contains that link target is in a module that is not in the compilation path.
• 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.

Could not resolve QML import statement for type <name>

QDoc issues this warning if you document a QML type, but omit the \inqmlmodule command. Example:

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \instantiates QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

Correct:

\qmltype ItemSelectionModel
\instantiates QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

\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.

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.

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:

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'

\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

Invalid regular expression:

\printuntil /^})$/

Valid regular expression:

\printuntil /^\}\)$/

The \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.

Multiple index files found for dependency <indexfile>:<depend>

Using <indexfile> as index file for dependency <depend>

Multiple -indexdir paths were passed to QDoc as command line options, and more than one contained an .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.

Cannot locate index file for dependency <depend>

Example:

"QMake" Cannot locate index file for dependency "activeqt"

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.

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.

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.

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.

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 \qml and {endqml-command}{\endqml}.

Example:

If there is a syntax error in the QML code, QDoc issues the warning

Unable to parse QML snippet: Syntax error at line 97, column 42

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

Unable to parse QML snippet: Expected token '{' at line 63, column 52

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.

Command <command> failed at end of file <filename>

Example:

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

In this case the warning means that the \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:

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

The \skipto + <pattern> moves the cursor to the next line containing that pattern. If \skipto doesn't find it, QDoc issues this warning.

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.

This page title exists in more than one file

The \title command sets the title for a page.

\page activeqt-server.html
\title Building ActiveX servers in Qt

QDoc issues this warning if a certain title is used in more than one page.

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:

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.]

No documentation generated for function <name> in global scope

QDoc was able to match the documentation for a function <name> to its declaration, but no output was generated because the function is declared in the global namespace.

Use the \relates command to associate the function with a documented type, namespace, or a header file. The function is then listed as a related non-member on the associated reference page.