diff options
Diffstat (limited to 'src/qdoc/qdoc/doc/qdoc-warnings.qdoc')
| -rw-r--r-- | src/qdoc/qdoc/doc/qdoc-warnings.qdoc | 839 |
1 files changed, 839 insertions, 0 deletions
diff --git a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc new file mode 100644 index 000000000..1be57f03d --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc @@ -0,0 +1,839 @@ +// 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 C++ class <ClassName> not found: \\instantiates <ClassName> + + If you describe a QML type, you may specify the class it instantiates. + Refer to the \l{instantiates-command}{\\instantiates} command in the + \l {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 + \l {internal-command}{\\internal}, or it originates from another + documentation module and QDoc did not locate an index file for the + corresponding dependency. + + See also \l {depends-variable}{depends}. + + \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 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 {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/component 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/component 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 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 <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 \\instantiates is only allowed in \\qmltype + + The \l{instantiates-command}{\\instantiates} 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 = "π" # 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 index: <filename> + + Example: + + \badcode + Failed to find index: path/to/QtCrator/appmanplugin/manual.index + \endcode + + In this case, it clearly means the indexes variable contains a + typo in the path of the index file. + + Incorrect: + \badcode + indexes += path/to/QtCrator/appmanplugin/manual.index + \endcode + + Correct: + \badcode + indexes += path/to/QtCreator/appmanplugin/manual.index + \endcode + + \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 + \instantiates QItemSelectionModel + \since 5.5 + \ingroup qtquick-models + \endcode + Correct: + \badcode + \qmltype ItemSelectionModel + \instantiates 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. + +*/ |