Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qdoc-warnings.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2021 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page qdoc-warnings.html
6
\previouspage Categories of Documentation
7
8
\title How to Resolve QDoc Warnings
9
10
QDoc may issue warnings when generating your documentation set.
11
This section describes what these warnings mean and how to resolve
12
them. This document does not describe warnings generated by Clang.
13
14
\section1 Can't link to <target>
15
16
QDoc issues this warning when one part of the documentation
17
(identified in the warning message) tries to refer to another,
18
but doesn't correctly specify that other, the target of the link.
19
This may arise because the reference to it is mistyped or because
20
the target has changed name (for a function or type) or title
21
(for another section).
22
23
Search the source code for that particular link target. If you get no
24
results, gradually make the search less specific until you find a match.
25
26
If the link target looks like the name of a type or function,
27
this could also be due to:
28
29
\list
30
\li The name (or, for functions, where specified, signature) used
31
where it is documented not matching the name used in its
32
declaration.
33
\li The link target being marked as \l {internal-command}{\\internal} when the linking
34
text was not.
35
\endlist
36
37
\section1 Found a \\target command outside table item in a table
38
39
If QDoc encounters a \l {target-command}{\\target command} that is not
40
preceded by an \\li command within a \l {table-command}
41
{\\table ... \\endtable block}, it issues this warning. The warning is
42
followed by the text
43
\e {Move the \\target inside the \\li to resolve this warning}.
44
45
\section1 Cannot find snippets file to quote from
46
47
QDoc issues this warning if it is unable to find the file named
48
after a \l {snippet-command}{\\snippet} or \l {quotefromfile-command}{\\quotefromfile} command.
49
50
Some useful steps for correcting this:
51
52
\list
53
\li Check if the snippet file name is correct. QDoc appends the
54
snippet file name to each of the directories given in the
55
search path, to get a path-name for a candidate file to look
56
for. It produces this error when none of these candidates exist.
57
\li Check the search path for snippets, given by the \c exampledirs
58
configuration variable in the \c{*.qdocconf} file. You may need
59
to add an entry to this path, or correct an existing entry.
60
\li Check if the snippet file exists, or if it has been moved, renamed
61
or removed, which may happen when there are changes to the source
62
code that QDoc tries to quote from.
63
\endlist
64
65
\section1 Unexpected \\snippet
66
67
QDoc issues this warning if it is unable to locate the snippet file
68
quoted in a \l {snippet-command}{\\snippet} command.
69
70
\section1 Undocumented QML <module> referred by <type> or its members
71
72
QDoc issues this warning if it is unable to locate a QML module
73
based on the identifier passed to the
74
\l {inqmlmodule-command}{\\inqmlmodule} or \l {qmlproperty-command}
75
{\\qmlproperty} commands associated with a QML \e type.
76
77
This means that either documentation for the \l {qmlmodule-command}
78
{\\qmlmodule} is missing, or an incorrect module identifier was
79
used in \\qmlproperty, \\qmlmethod, or \\qmlsignal command(s).
80
81
\section1 No such <type> in QML <module>
82
83
QDoc issues this warning if a \l {qmlproperty-command} {\\qmlproperty},
84
\l {qmlmethod-command} {\\qmlmethod}, or \l {qmlsignal-command}
85
{\\qmlsignal} command argument uses a QML module identifier, but
86
the associated \l {qmltype-command}{\\qmltype} does not belong to
87
that module.
88
89
The QML module identifier, if defined, \b must match with the
90
\l {inqmlmodule-command} {\\inqmlmodule} argument in the QML type
91
documentation. In most cases, QDoc is able to locate the QML type
92
without a module identifier.
93
94
\section1 Undocumented return value
95
96
For functions whose return-type is not void, QDoc checks if the return
97
value is documented. This warning is issued if the documentation for a
98
function or method doesn't contain a word starting with "return".
99
100
\section1 Undocumented parameter
101
102
QDoc requires the documentation of a function or method to describe
103
every parameter. It recognizes this by each parameter name (as
104
specified where the function or method is declared in a header file)
105
appearing after a \l {a-command}{\\a} command.
106
107
This requirement is not imposed for function overload documentation,
108
provided that the overload is marked with the \qdoccmd overload command
109
and a fully-documented function with the same name exists.
110
111
\section1 No such parameter
112
113
QDoc issues this warning when the parameter name given after an
114
\l{a-command}{\\a} command does not match any of the parameters named
115
in the header-file's declaration of the function or method being
116
documented.
117
118
\section1 Unknown macro
119
120
QDoc issues this warning when it sees a backslash, \c{\}, followed
121
by a token it doesn't recognize as the name of either a built-in command
122
or a \l {macro-variable}{user-defined macro}. When quoting code
123
that contains character escape sequences, you should enclose the
124
code in \\c{...} to prevent this warning against the escape sequences.
125
126
\section1 Failed to find function when parsing \\fn <signature>
127
128
When Clang parses a function signature following an \qdoccmd fn command,
129
it checks this against the declaration in the header file. If Clang
130
discovers discrepancies, it issues this warning message.
131
132
The signature must be fully qualified. Typical issues include missing or
133
incorrect template arguments, return type, or qualifiers such as
134
\e const.
135
136
\note The \c{\fn} signature for a \e {hidden friend} should be
137
fully qualified with the scope of the class that declares
138
the function.
139
140
\section1 QML type <TypeName> documented with <ClassName> as its native type. Replacing <ClassName> with <OtherClass>
141
If the \qdoccmd nativetype command is used with the same argument in
142
multiple QML type documentation comments that belong to the same
143
documentation project, QDoc issues this warning. To resolve this, ensure
144
that you use the \c {\nativetype} command only once for each C++ class.
145
146
147
\section1 Cannot tie this documentation to anything
148
149
QDoc found a \beginqdoc ... \endqdoc comment, with no \l{Topic Commands}{topic command}, that was
150
not immediately followed by a class, function or property definition.
151
It thus does not know what the comment documents.
152
153
\section1 This qdoc comment contains no topic command (e.g., \\module, \\page)
154
155
If a QDoc comment doesn't contain a \l {Topic Commands}{topic command}, QDoc does
156
not know what the comment documents, and issues this warning.
157
Very similar to \l {Cannot tie this documentation to anything}, but
158
specific to comments that are not in C++ or QML files.
159
160
\section1 <name> documented more than once
161
162
QDoc issues this warning when it finds two comments that
163
document the same item. The location of the previously seen
164
comment is provided in warning details.
165
166
For example, you see this warning when a function has a documentation
167
comment preceding its definition, and a separate \\fn comment
168
elsewhere.
169
170
\section1 Namespace <name> documented more than once
171
172
This warning means that a documentation set contains two comments
173
containing \l {namespace-command}{\\namespace} commands with the same
174
argument, <name>.
175
176
\section1 <name> is documented, but namespace <namespace> is not documented in any module
177
178
The documentation for \e {<name>} was found, but \e{<name>} is declared
179
under a namespace that is either undocumented or QDoc was unable to
180
locate the documentation for it.
181
182
This can be resolved by either documenting \e{<namespace>}, or if it is
183
already documented in another module, ensure that this module has
184
a dependency to it.
185
186
See also \l {depends-variable}{depends} and {indexes-variable}{indexes}.
187
188
\section1 Has no \\inmodule command
189
190
QDoc issues this warning if the QDoc comments do not relate
191
a class, namespace, or headerfile to a module with the
192
\l{inmodule-command}{\\inmodule} command.
193
194
If the QDoc comment describes an entity that's not a member of
195
some other entity (typically a namespace or class), it should use
196
either \l {relates-command}{\\relates} or \l {inmodule-command}{\\inmodule}
197
to associate it with its broader context. This warning is raised
198
if it does not.
199
200
\section1 Cannot find <name> specified with \<command> in any header file
201
202
This means that QDoc cannot find a declaration of <name> in any
203
header file, but has found a comment that claims to document it.
204
205
An example:
206
\badcode
207
Cannot find 'Color::Red' specified with '\enum' in any header file.
208
\endcode
209
210
A documentation comment claims to describe an enum, but QDoc didn't
211
find a definition of that enum in a header file.
212
213
This may also be due to:
214
215
\list
216
\li a typo in <name> or <command>
217
\li a missing namespace-or-class prefix
218
\li <name> having moved to another namespace or class
219
\endlist
220
221
\section1 Unrecognizable QML module/component qualifier for <identifier>
222
223
A parameter passed to \l {qmlproperty-command}{\\qmlproperty} or
224
\l {qmlmethod-command}{\\qmlmethod} contains a combination of
225
qmlModule::qmlType::identifier that is not defined anywhere.
226
227
Example:
228
\badcode
229
Unrecognizable QML module/component qualifier for real QtQuick::DragHandler::DragAxis::minimum
230
\endcode
231
232
DragHandler doesn't have a property called DragAxis.
233
234
\section1 Missing property type for <name>
235
236
A declaration of a \l {qmlproperty-command}{\\qmlproperty} is missing its property type.
237
238
The \\qmlproperty command expects to be followed by the property type, then the
239
fully-qualified name of the property (i.e. the name ::-joined after the name of the
240
class it belongs to).
241
242
Incorrect:
243
\badcode
244
\qmlproperty MyWidget::count
245
\endcode
246
247
Correct:
248
\badcode
249
\qmlproperty int MyWidget::count
250
\endcode
251
252
\section1 QML property documented multiple times: <identifier>
253
254
QDoc uses this warning when it finds two QDoc comments that document
255
the same QML property, either by appearing just before its definition,
256
or using the \l {qmlproperty-command}{\\qmlproperty} command.
257
258
\section1 Command <command> not allowed with QML property commands
259
260
Example:
261
262
\badcode
263
\qmlproperty real QtQuick.Controls::RangeSlider::first.value
264
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
265
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
266
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
267
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()
268
\endcode
269
270
Error message:
271
272
\badcode
273
Command '\\qmlsignal' not allowed with QML property commands
274
\endcode
275
276
This warning is specific to property group documentation. QDoc
277
allows multiple qmlproperty or qmlattachedproperty topic commands
278
in a single documentation comment to document a property group
279
where the last element in the path is <group>.<property>. Any other topic
280
commands triggers this warning.
281
282
\section1 Cannot find base function for <method> in <class>
283
284
QDoc produces this warning if \\reimp is used to document a method,
285
as an override of a virtual method, when no base class has a virtual
286
method with the given name and signature. This may happen because
287
the method it was written to override has changed its signature, or is
288
no longer virtual.
289
290
\section1 Illegal \\reimp; no documented virtual function for <command>
291
292
Qdoc tries to create a link to the function that this one reimplements,
293
but it could not find the link target, likely because that
294
function is not documented. This can also arise if no base class
295
has a virtual method with this name and signature; which might
296
arise due to a renaming, a change in signature or the base no
297
longer declaring it virtual.
298
299
\section1 <class> tries to inherit itself
300
301
The \l {inherits-command}{\\inherits} command is used to document that a QMl type
302
inherits some other QML type. This warning is issued if that other
303
QML type is the same as the QML type documented.
304
305
Example:
306
307
\badcode
308
\qmltype Foo
309
\inherits Foo
310
\endcode
311
312
\section1 \\nativetype is only allowed in \\qmltype
313
314
The \l{nativetype-command}{\\nativetype} command can only be used in a QDoc
315
comment that documents a QML type.
316
317
\section1 All properties in a group must belong to the same type: <name>
318
319
When documenting QML property groups, all properties listed in
320
the comment block must belong to the same QML type.
321
322
\section1 Cannot find project file for example <name>
323
324
In the example's source directory, QDoc expects to find a project
325
file named \c{CMakeLists.txt}, or a file with a \c{.pro}, \c{.qmlproject}, or
326
\c{.pyproject} extension where the base name matches that of the example
327
directory. For example, \c {examples/mymodule/helloworld/helloworld.pro}.
328
329
\section1 Cannot open file to quote from: <filename>
330
331
The search path for <filename> is defined by the following
332
variables in the \c{.qdocconf} file: \c{sources}, \c{sourcedirs},
333
and \c{exampledirs}.
334
335
QDoc failed to find a file named in a command (such as
336
\l {quotefromfile-command}{\\quotefromfile},
337
\l {snippet-command}{\\snippet}, \l {include-command}{\\include})
338
that tells it to retrieve content from the named file. It searches
339
each directory named in the search path. If there is no file with
340
this name in any of those directories, or the file is found but not
341
readable, QDoc issues this warning. Check that the combination of
342
search path and <filename> is correctly spelled, and that you have
343
read permissions for the file.
344
345
\note <filename> may include a directory name prefix; the whole
346
<filename> is appended to each directory in the search path.
347
348
\sa {Cannot find qdoc include file <filename>}
349
350
\section1 Missing format name after \\raw
351
352
The \l {raw-command}{\\raw} command and the corresponding \l {raw-command}{\\endraw}
353
command delimit a block of raw mark-up language code. The \\raw
354
command must be followed by the format name.
355
356
\section1 Macro cannot have both format-specific and qdoc-syntax definitions
357
358
A \l {macro-variable}{\\macro} that specifies an output format cannot also
359
have a generic definition.
360
361
An example of a configuration that triggers this warning:
362
363
\badcode
364
macro.gui = \b
365
macro.gui.HTML = "<b>\1</b>"
366
\endcode
367
368
\section1 Unknown command <name>
369
370
When a QDoc comment uses a backslash followed by a token that is not a QDoc
371
built-in command and has not been defined as a custom command
372
\l {macro-variable}{macro}, QDoc produces this warning. Check the spelling
373
of the command name, and check whether your QDoc configuration doesn't
374
include whatever would have defined it, if it's a custom command.
375
376
This may also be produced due to code being quoted in the QDoc comment,
377
for example the author may have referred to the C string termination
378
character \c{'\0'} or one of the other C string escape sequences such
379
as \c{'\n'} without escaping the backslash. Escape the backslash
380
as \c{\} to include a literal backslash in the documentation, or
381
enclose the code fragment in \c{\c{...}}, which suppresses
382
interpretation of backslashes as introducing QDoc commands.
383
384
\section1 Duplicate target name <target>
385
386
This warning is issued if you define two targets with the same parameter,
387
using either the \l {target-command}{\\target} or the \l {keyword-command}
388
{\\keyword} command. The target name given as parameter to these commands
389
must be unique. The warning is followed by "The previous occurrence is
390
here: [location]", where location contains a file name and line number.
391
392
\section1 Cannot find qdoc include file <filename>
393
394
QDoc failed to find an include file named in a command.
395
QDoc searches each directory named in the search path.
396
If there is no file with this name in any of those directories,
397
or the file found in that search is not readable, QDoc issues
398
this warning. Check that the combination of search path and
399
<filename> is correctly spelled, and that you have read permissions
400
for the file.
401
402
\note <filename> may include a directory name prefix; the whole
403
<filename> is appended to each directory in the search path.
404
405
\sa {Cannot open file to quote from: <filename>}
406
407
\section1 Cannot find <tag> in <file>
408
409
This means QDoc cannot find the identifier <id> in the
410
\l{include-command}{\\include} <file> or {snippet-command}{\\snippet} <file>.
411
412
\section1 Empty qdoc snippet <tag> in <file>
413
414
The snippet <tag> was found in the \l {snippet-command}{\\snippet} <file>, but it is empty.
415
416
\section1 Cannot nest <command> commands
417
418
This warning concerns formatting commands: bold, italic,
419
index, link, span, subscript, superscript, teletype, uicontrol,
420
underline. A formatting command cannot be used within the text
421
it applies to. An example of this:
422
423
\badcode
424
There is \b{no \b{super-}bold}.
425
\encode
426
427
\section1 Can't use <inner> in <outer>
428
429
This warning is issued for commands that cannot be nested.
430
431
Example:
432
\badcode
433
\list
434
\li \table
435
\row \li Hello \li Hi
436
\endtable
437
\endlist
438
\endcode
439
440
Results in the QDoc warning "Can't use '\\table' in '\\list'".
441
442
\section1 Missing <outer> before <inner>
443
444
Some examples:
445
446
\list
447
\li The \l {li-command}{\\li} command can only be used inside a \l {list-command}{\\list}
448
or a \l {row-command}{\\row} of a \l {table-command}{\\table}.
449
\li The \l {row-command}{\\row} and \l {header-command}{\\header} commands can only be
450
used within a \l {table-command}{\\table}.
451
\endlist
452
453
\section1 Unexpected <end_command>
454
455
This warning is issued if, for example, you have an \l {list-command}{\\endlist} without
456
a preceding \l {list-command}{\\list}. It applies to all commands that come in pairs (e.g.
457
startFoo/endFoo).
458
459
\section1 Missing comma in \\sa
460
461
The titles listed for a \l {sa-command}{\\sa} command should be separated
462
from one another with commas.
463
464
\section1 Macro <command> does not have a default definition
465
466
QDoc is attempting to expand a macro, and expects that macro to
467
have a default definition. Some macros may only have format-specific
468
definitions.
469
470
Example:
471
\badcode
472
macro.pi.HTML = "π" # encodes the pi symbol for HTML output format
473
\endcode
474
475
There are however instances where macro expansion requires a
476
format-independent macro. For example, you can have macros in
477
section titles, but they must have default definitions.
478
479
\section1 Macro <macro> invoked with too few arguments (expected <many>, got <few>)
480
481
The given macro needs more parameters than it was given. See
482
the definition of the macro in the configuration for further
483
details.
484
485
\section1 Unbalanced parentheses in <text>
486
487
Points to a '(' without a corresponding ')', or vice versa.
488
489
\section1 No documentation for <name>
490
491
Example:
492
493
\badcode
494
Warning "No documentation for QNativeInterface."
495
\endcode
496
497
QDoc detects the declaration of namespace QNativeInterface in
498
a header file, but does not find a QDoc comment where that
499
namespace has been documented.
500
501
\section1 No such enum item <name> in <class>
502
503
Example:
504
505
\badcode
506
Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
507
with \enum in any header file.
508
\endcode
509
510
QDoc issues this warning when it finds a \l{value-command}{\\value} directive in an
511
\l{enum-command}{\\enum} comment that names a value not found in the header file that declared
512
the enumerated type documented.
513
514
\section1 Undocumented enum item <enum> in <enum list>
515
516
<enum list>'s \l {value-command}{\\value} or \l {omitvalue-command}{\\omitvalue} entries
517
did not include one for \l {enum-command}{<enum>}, which is named in the
518
declaration of <enum list> in the header file.
519
520
\section1 Failed to find qhp.<project>.subprojects.<subproject>.indexTitle
521
522
QDoc failed to find a title for a page designated as the index page
523
for <subproject> in the Qt help project configuration.
524
525
Subproject index titles must be local to the current documentation project.
526
Using a page title from another project, loaded as a dependency, also
527
results in this warning.
528
529
For more information, see \l {Creating Help Project Files}.
530
531
\section1 \\generatelist <group> is empty
532
533
Below a short overview of all possible arguments for \l {generatelist-command}{\\generatelist}:
534
\list
535
\li \\generatelist annotatedexamples
536
\li \\generatelist annotatedattributions
537
\li \\generatelist classes <prefix>
538
\li \\generatelist classesbymodule <module name>
539
\li \\generatelist qmltypesbymodule <module name>
540
\li \\generatelist functionindex
541
\li \\generatelist legalese
542
\li \\generatelist overviews
543
\li \\generatelist attributions
544
\li \\generatelist related
545
\endlist
546
547
QDoc issues this warning if you specify \c{\generatelist <group>}
548
and the group does not contain any items, or if you specify
549
\c{\generatelist <group> <pattern>} and no item in the group
550
matches the pattern.
551
552
\section1 \\generatelist <group> no such group
553
554
This warning issues if the argument to \l {generatelist-command}{\\generatelist}
555
is a non-existing group.
556
557
Example:
558
559
\code
560
\generatelist draganddrop
561
\endcode
562
563
This statement generates a list of classes or QML types in the
564
draganddrop group. Classes or QML types are added to the
565
draganddrop group by the \c{\l {ingroup-command}{\ingroup} draganddrop} command in their
566
\l {class-command}{\\class} or \l {qmltype-command}{\\qmltype} comment.
567
568
QDoc issues this warning message if no entity has
569
this \c{\ingroup draganddrop} statement.
570
571
\section1 Missing image: <imagefile>
572
573
The search path to the image is wrong, or the image file does not exist.
574
575
\section1 Can't link to <target>
576
577
This can have a variety of causes:
578
579
\list
580
\li The link target has not been defined with a QDoc topic command,
581
e.g. {title-command}{\\title} <target>.
582
\li The <target> contains a typo.
583
\li The document that contains that link target did not get compiled.
584
\li The document that contains that link target is in a module that is
585
not in the compilation path.
586
\li The link target is in another module, and a dependency to that
587
module was not set in the configuration or QDoc failed to locate
588
the index file for the dependency.
589
\endlist
590
591
\section1 Could not resolve QML import statement for type <name>
592
593
QDoc issues this warning if you document a QML type, but omit
594
the \l{inqmlmodule-command}{\\inqmlmodule} command.
595
Example:
596
597
\badcode
598
Could not resolve QML import statement for type 'ItemSelectionModel'
599
\encode
600
601
Incorrect:
602
\badcode
603
\qmltype ItemSelectionModel
604
\nativetype QItemSelectionModel
605
\since 5.5
606
\ingroup qtquick-models
607
\endcode
608
Correct:
609
\badcode
610
\qmltype ItemSelectionModel
611
\nativetype QItemSelectionModel
612
\inqmlmodule QtQml.Models
613
\since 5.5
614
\ingroup qtquick-models
615
\endcode
616
617
\section1 \\brief statement does not end with a full stop
618
619
The argument to the \\brief command is a sentence, summarizing
620
the topic documented, so should end in a full stop. It should
621
also be brief.
622
623
\section1 QtDeclarative not installed; cannot parse QML
624
625
QDoc issues this warning if it has been compiled without support
626
for QML parsing. This should not happen unless you have a
627
custom build of QDoc.
628
629
\section1 Invalid regular expression <regex>
630
631
Some QDoc commands take regular expressions as parameters. QDoc
632
gives this warning when the text given as such a parameter is not
633
a valid regular expression, usually due to it containing characters
634
with special meanings in regular expressions, that should have been
635
escaped.
636
637
Example:
638
639
\badcode
640
notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'
641
\endcode
642
643
\badcode
644
\quotefromfile webenginewidgets/notifications/data/index.html
645
\skipuntil resetPermission
646
\endcode
647
648
Invalid regular expression:
649
\badcode
650
\printuntil /^})$/
651
\endcode
652
653
Valid regular expression:
654
\badcode
655
\printuntil /^\}\)$/
656
\endcode
657
658
659
The \l {printuntil-command}{\\printuntil} command prints until it
660
meets a line consisting of only a right curly brace followed by a
661
right parenthesis. In this case, the curly brace and the parenthesis
662
need to be escaped because they have special meanings in regular
663
expressions.
664
665
\section1 Multiple index files found for dependency <indexfile>:<depend>
666
Using <indexfile> as index file for dependency <depend>
667
668
Multiple \c{-indexdir} paths were passed to QDoc as command line options,
669
and more than one contained an \c{.index} file that matches a dependency.
670
QDoc picks the one with the latest timestamp automatically.
671
672
Typically, this warning indicates that there are build artifacts left
673
from a previous documentation build.
674
675
\section1 Cannot locate index file for dependency <depend>
676
677
Example:
678
679
\badcode
680
"QMake" Cannot locate index file for dependency "activeqt"
681
\endcode
682
683
The documentation project QMake could not locate activeqt.index
684
in any of the specified index directories. In this case, the
685
specified index directories are specified in qmake.qdocconf.
686
687
\section1 Dependent modules specified, but no index directories were set.
688
689
QDoc expected to see one or more -indexdir arguments on the command line.
690
Without them, QDoc cannot locate the index files of any dependencies
691
defined with the 'depends' configuration variable.
692
693
\section1 Overrides a previous doc
694
695
QDoc issues this warning when it finds two comments that appear to
696
describe the same entity. The location of the previously seen
697
comment is provided in warning details.
698
699
\section1 Unrecognized list style <name>
700
701
\\list can take an optional argument: a single number or character
702
that modifies the list style. Refer to the {list-command}{\\list}
703
documentation for more details. If you use an argument that is
704
not recognized, QDoc issues this warning.
705
706
\section1 Unable to parse QML snippet: <code> at line <y>, column <x>
707
708
QDoc comments can contain QML code. This code can be found in a snippet,
709
or in the QDoc comments delimited by \l {qml-command}{\\qml} and {endqml-command}{\\endqml}.
710
711
Example:
712
713
If there is a syntax error in the QML code, QDoc issues the warning
714
\badcode
715
Unable to parse QML snippet: Syntax error at line 97, column 42
716
\endcode
717
718
Snippets can also contain QML and also there the code is checked. If there is
719
for example a missing curly brace in the code, QDoc issues the warning
720
\badcode
721
Unable to parse QML snippet: Expected token '{' at line 63, column 52
722
\endcode
723
724
QDoc often fails to parse incomplete QML snippets; in these cases,
725
it's often OK to replace the \\qml ... \\endqml commands with
726
\\code ... \\endcode to suppress this warning.
727
728
\section1 Command <command> failed at end of file <filename>
729
730
Example:
731
732
\badcode
733
Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".
734
\endcode
735
736
In this case the warning means that the \l {snippet-command}{\\snippet} command did not find a second
737
label "\/\/! [2]" to mark the end of the snippet. It could also mean that it didn't
738
find any occurrence of that snippet tag in this snippet file.
739
740
Another example:
741
742
\badcode
743
Command '\skipto' failed at end of file 'styling/CMakeLists.txt".
744
\endcode
745
746
The \l {skipto-command}{\\skipto} + <pattern> moves the cursor to the next line containing
747
that pattern. If \\skipto doesn't find it, QDoc issues this warning.
748
749
\section1 Failed to open <file> for writing
750
751
This warning clearly means it cannot open a file for writing, probably because
752
of a wrong path, or permission to write in a certain directory.
753
754
\section1 This page title exists in more than one file
755
756
The \l {title-command}{\\title} command sets the title for a page.
757
758
\code
759
\page activeqt-server.html
760
\title Building ActiveX servers in Qt
761
\endcode
762
763
QDoc issues this warning if a certain title is used in more than one page.
764
765
766
\section1 The content is too long
767
768
QDoc uses a fixed-size buffer when tokenizing source files. If any single
769
token in the file has more characters than the maximum limit, QDoc issues
770
this warning.
771
772
While QDoc continues parsing the file, only the part of the token that
773
fits into the buffer is considered, meaning that the output might be
774
mangled.
775
776
To resolve this warning, the relevant content must be reduced in size,
777
either by splitting it, if possible, or by removing some of its parts.
778
779
The maximum amount of characters for a single token is shown alongside
780
the warning, for example:
781
782
\badcode
783
file.qdoc:71154: (qdoc) warning: The content is too long.
784
785
[The maximum amount of characters for this content is 524288.
786
Consider splitting it or reducing its size.]
787
\endcode
788
789
\note Since content that is too long is not parsed in full, QDoc may
790
issue warnings that are false positives. Resolve all warnings of this type
791
before fixing other warnings.
792
793
\section1 No documentation generated for function <name> in global scope
794
795
QDoc was able to match the documentation for a function \e {<name>} to its
796
declaration, but no output was generated because the function is declared
797
in the global namespace.
798
799
Use the \l {relates-command}{\\relates} command to associate the function
800
with a documented type, namespace, or a header file. The function is then
801
listed as a \e {related non-member} on the associated reference page.
802
803
\section1 Documentation configuration for <project> doesn't define a help project (qhp)
804
805
A valid Qt help configuration was expected but not provided in the project's
806
.qdocconf file.
807
808
See also \l{Creating Help Project Files} and \l {qhp-variable}{qhp}.
809
810
\section1 Already generated FILE for this project
811
812
While generating the documentation for a project, QDoc keeps track of the
813
file names of the files it has generated. QDoc will issue a warning when it
814
opens a file for writing if that file is known to have been generated
815
previously, in the current execution. This can happen if a \qdoccmd page
816
command uses the same name as \qdoccmd group, for example.
817
818
You can set the environment variable \c QDOC_ALL_OVERWRITES_ARE_WARNINGS to
819
unconditionally warn about all such events. This may be useful when tracking
820
down the offending definitions.
821
822
*/
qttools
src
qdoc
qdoc
doc
qdoc-warnings.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0