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-manual-contextcmds.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page 14-qdoc-commands-contextcommands.html
6 \previouspage Topic Commands
7 \nextpage Document Navigation
8
9 \title Context Commands
10
11 The context commands provide information about the element being
12 documented that QDoc can't deduce on its own. For example:
13 \list
14 \li Is this class thread-safe?
15 \li Is this function reentrant?
16 \li Of which module is this class a member?
17 \li Which include statement is needed to use this class?
18 \endlist
19
20 Context commands can appear anywhere in a QDoc comment,
21 but they are normally placed near the top of the comment, just
22 below the \l {Topic Commands} {topic} command.
23
24 \list
25 \li \l {abstract-command} {\\abstract}
26 \li \l {attribution-command} {\\attribution}
27 \li \l {cmakecomponent-command} {\\cmakecomponent}
28 \li \l {cmakepackage-command} {\\cmakepackage}
29 \li \l {cmaketargetitem-command} {\\cmaketargetitem}
30 \li \l {compares-command}{\\compares} (Since QDoc 6.7)
31 \li \l {compareswith-command}{\\compareswith} (Since QDoc 6.7)
32 \li \l {default-command} {\\default}
33 \li \l {deprecated-command}{\\deprecated}
34 \li \l {ingroup-command}{\\ingroup}
35 \li \l {inheaderfile-command}{\\inheaderfile}
36 \li \l {inherits-command}{\\inherits}
37 \li \l {inmodule-command}{\\inmodule}
38 \li \l {internal-command}{\\internal}
39 \li \l {modulestate-command} {\\modulestate} (Since QDoc 6.5)
40 \li \l {nextpage-command}{\\nextpage}
41 \li \l {nonreentrant-command}{\\nonreentrant}
42 \li \l {overload-command}{\\overload}
43 \li \l {preliminary-command}{\\preliminary}
44 \li \l {previouspage-command}{\\previouspage}
45 \li \l {qmlabstract-command} {\\qmlabstract}
46 \li \l {qmldefault-command} {\\qmldefault}
47 \li \qdoccmd qmlenumeratorsfrom (Since QDoc 6.8)
48 \li \l {qtcmakepackage-command} {\\qtcmakepackage}
49 \li \l {qtcmaketargetitem-command} {\\qtcmaketargetitem}
50 \li \l {readonly-command} {\\readonly}
51 \li \l {reentrant-command}{\\reentrant}
52 \li \l {reimp-command}{\\reimp}
53 \li \l {relates-command}{\\relates}
54 \li \l {required-command} {\\required}
55 \li \l {since-command}{\\since}
56 \li \l {startpage-command}{\\startpage}
57 \li \l {subtitle-command}{\\subtitle}
58 \li \l {threadsafe-command}{\\threadsafe}
59 \li \l {title-command}{\\title}
60 \li \l {toc-command}{\\toc} (Since QDoc 6.11)
61 \li \l {tocentry-command}{\\tocentry} (Since QDoc 6.11)
62 \li \l {wrapper-command}{\\wrapper}
63 \endlist
64
65*/
66
67/*!
68 \page 15-qdoc-commands-navigation.html
69 \previouspage Context Commands
70 \nextpage Status
71
72 \title Document Navigation
73
74 The navigation commands are for linking the pages of a document in
75 a meaningful sequence. Below is a sequence of QDoc comments that
76 shows a typical use of the navigation commands.
77
78 \section1 Example
79 \quotefile files/basicqt.qdoc.sample
80
81 The \l {startpage-command} {\\startpage} command creates a link to
82 the page the author wants as the first page of a multipage document.
83
84 The link is included in the generated HTML source code but has no
85 visual effect on the documentation:
86
87 \code
88 <head>
89 ...
90 <link rel="start" href="basicqt.html" />
91 ...
92 </head>
93 \endcode
94
95 \section1 Commands
96
97 \target previouspage-command
98 \section2 \\previouspage
99
100 The \\previouspage command links the current page to the previous
101 page in a sequence. The command has two arguments, each enclosed
102 by curly braces: the first is the link target (the title of
103 the previous page), the second is the link text. If the page's
104 title is equivalent to the link text, the second argument can be
105 omitted.
106
107 The command must stand alone on its own line.
108
109 \target nextpage-command
110 \section2 \\nextpage
111
112 The \\nextpage command links the current page to the next page in
113 a sequence. The command follows the same syntax and argument
114 convention as the \l {previouspage-command} {\\previouspage}
115 command.
116
117 \target startpage-command
118 \section2 \\startpage
119
120 The \\startpage command specifies the first page of a sequence of
121 pages. The command must stand alone on its own line, and its
122 unique argument is the title of the first document.
123
124 QDoc will generate a link to the start page and include it in the
125 generated HTML file, but this has no visual effect on the
126 documentation. The generated link type tells browsers and search
127 engines which document is considered by the author to be the
128 starting point of the collection.
129
130 \target toc-command
131 \section2 \\toc
132
133 The \\toc and \\endtoc commands specify a list of sub-topics
134 (pages) for the topic the command appears in. A table of contents
135 (TOC) hierarchy is generated for the entire documentation
136 project based on the TOC entries on each topic.
137
138 Within the \\toc .. \\endtoc block, use \qdoccmd {tocentry} commands
139 to specify the sub-topics by title. Like the \qdoccmd {l} (link)
140 command, \\tocentry takes an optional second argument for the
141 user-visible title in the generated TOC entry.
142
143 \badcode *
144 /\1!
145 \page index.html
146 \title Qt
147 ...
148 \toc
149 \tocentry {Introduction to Qt} {Introduction}
150 \tocentry {What's new in Qt} {What's new}
151 \tocentry {Getting started}
152 \endtoc
153 \1/
154 \endcode
155
156 \\toc commands cannot be nested. However, each sub-topic can specify
157 their own TOC entries. A topic can use only one \\toc command.
158
159 QDoc writes the resulting table of contents structure in XML format
160 to a \e {<project>_toc.xml} file.
161
162 \note The root topic (index or landing page) must be specified in the project
163 configuration with either \c {navigation.landingpage} or \c
164 {navigation.homepage}. See \qdocvar navigation for more information.
165
166 The \\toc command was introduced to QDoc with Qt 6.11.
167
168 See also \qdoccmd {tocentry}.
169
170 \target tocentry-command
171 \section2 \\tocentry
172
173 Specifies a sub-topic (page) as an entry in table of contents. Can only be
174 used inside a pair of \\toc and \\endtoc commands.
175
176 The \\tocentry command was introduced to QDoc with Qt 6.11.
177
178 See also \qdoccmd {toc}.
179*/
180
181/*!
182 \page 16-qdoc-commands-status.html
183 \previouspage Document Navigation
184 \nextpage Thread Support
185
186 \title Status
187
188 These commands are for indicating that a documented element has
189 some special status. The element could be marked \e deprecated,
190 that is, it's about to be made obsolete and no longer included
191 in the public interface. The \l {since-command}{\\since} command
192 is for specifying the version number in which a function or class
193 first appeared. The \l {qmlabstract-command} {\\qmlabstract} command
194 is for marking a QML type as an abstract base class.
195
196 \target abstract-command
197 \target qmlabstract-command
198 \section1 \\abstract and \\qmlabstract
199
200 \\abstract is a synonym for the \\qmlabstract command. Add this
201 command to the \l {qmltype-command} {\\qmltype} comment for a QML
202 type when that type is meant to be used \e {only} as an abstract
203 base type. When a QML type is abstract, it means that the QML type
204 that can't be instantiated. Instead, the properties in its public
205 API are included in the public properties list on the reference
206 page for each QML type that inherits the abstract QML type. The
207 properties are documented as if they are properties of the
208 inheriting QML type.
209
210 Normally, when a QML type is marked with \e{\\qmlabstract}, it is
211 also marked with \e{\\internal} so that its reference page is not
212 generated. It the abstract QML type is not marked internal, it
213 will have a reference page in the documentation.
214
215 \target attribution-command
216 \section1 \\attribution
217
218 The \\attribution command marks a documented \qdoccmd page as license
219 attribution documentation.
220
221 The \l {annotatedattributions} {\\generatelist annotatedattributions}
222 command generates an annotated list of all license attribution pages
223 in the documentation project.
224
225 \target default-command
226 \section1 \\default
227
228 The \\default command is used for documenting a default value for
229 a QML property. The command takes a single argument, which is
230 displayed in the documentation as the default value.
231
232 \badcode *
233 /\1!
234 \qmlproperty real Item::x
235 \default 0.0
236 \1/
237 \endcode
238
239 If the default value is a non-empty string, use quotes:
240
241 \badcode *
242 /\1!
243 \qmlproperty string Item::state
244 \default "invalid"
245 \1/
246 \endcode
247
248 \target compares-command
249 \section2 \\compares
250
251 Use the \c {\compares} command to describe the comparison results for the
252 documented C++ type when compared to itself. You must use this command in
253 conjunction with the \l {class-command}{\\class} command.
254
255 \c {\compares} takes one of the following arguments:
256
257 //! [comparison-categories]
258 \list
259 \li \c strong
260 \li \c partial
261 \li \c weak
262 \li \c equality
263 \endlist
264
265 \c {strong}, \c {partial}, and \c {weak} relate to the ordering.
266 \c {equality} means that the type is only compared for equality.
267 //! [comparison-categories]
268
269 This command was introduced to QDoc with Qt 6.7.
270
271 See also \l {compareswith-command}{\\compareswith}.
272
273 \target compareswith-command
274 \section1 \\compareswith
275
276 Use the \c {\compareswith .. \endcompareswith} pair of commands to
277 describe the comparison results for the documented C++ type when
278 compared to other types. \c {\compareswith} takes two or more
279 arguments: a comparison category, followed by a type name, or a
280 space-separated list of type names. Any text lines between
281 \c {\compareswith} and \c {\endcompareswith} commands are
282 considered further details that apply to all types subject
283 to the comparison category argument.
284
285 Types that have one or more space in their name, such as
286 \c{unsigned long}, should be enclosed in braces.
287
288 For example:
289
290 \badcode *
291 /\1!
292 ...
293 \compareswith strong int long {unsigned long} {unsigned int} char
294 ...
295 \endcompareswith
296 ...
297 \1/
298 \endcode
299
300 Argument enclosed in braces have their leading and trailing whitespaces
301 removed.
302 For example, \c{unsigned long} and \c{ unsigned long } are equivalent.
303
304 The comparison category argument must be one of the following:
305 \include qdoc-manual-contextcmds.qdoc comparison-categories
306
307 This command was introduced to QDoc with Qt 6.7.
308
309 See also \l {compares-command}{\\compares}.
310
311 \target qmldefault-command
312 \section1 \\qmldefault
313
314 The \\qmldefault command is for marking a QML property as the
315 \l {default-properties}
316 {default property}. The word \c default is displayed in
317 the documentation of the property.
318
319 \badcode *
320 /\1!
321 \qmlproperty list<Change> State::changes
322 This property holds the changes to apply for this state.
323 \qmldefault
324
325 By default, these changes are applied against the default state. If the state
326 extends another state, then the changes are applied against the state being
327 extended.
328 \1/
329 \endcode
330
331 See how QDoc renders this property on the reference page for the
332 \l {QtQuick::State::changes}{State} type.
333
334 \target qmlenumeratorsfrom-command
335 \section1 \\qmlenumeratorsfrom
336
337 Use the \\qmlenumeratorsfrom command in a \qdoccmd qmlproperty topic
338 with a property type \e enumeration, to automatically replicate the
339 documentation for enumerators from a C++ \qdoccmd enum topic.
340
341 The command takes a fully qualified C++ enum as an argument,
342 and generates a list of enumerators and their descriptions.
343
344 \note The C++ enum must be documented in the same project; QDoc
345 cannot access its documentation if it's part of an external
346 documentation set that the current project \qdocvar depends
347 on.
348
349 By default, each enumerator is prefixed with the type name the
350 property belongs to, with \c{.} as the separator.
351
352 For example:
353
354 \badcode *
355 /\1!
356 \qmlproperty enumeration QtMultimedia::Camera::error
357 \qmlenumeratorsfrom QCamera::Error
358
359 //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
360 \1/
361 \endcode
362
363 If the enumerators are registered to QML under a different type
364 name, this name (prefix) can be specified using the optional
365 argument in square brackets:
366
367 \badcode
368 \qmlenumeratorsfrom [Errors] QCamera::Error
369
370 //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
371 \1/
372 \endcode
373
374 This command was introduced in QDoc 6.8.
375
376 See also \qdoccmd {qmlproperty}, \qdoccmd {enum}, and \qdoccmd {value}.
377
378 \target dontdocument-command
379 \section1 \\dontdocument
380
381 The \\dontdocument command is only used in a dontdocument.qdoc file
382 for a particular module. This file specifies publically declared
383 classes or structs that are not meant to be documented. QDoc will
384 not print warnings about missing \\class comments for these classes
385 and structs.
386
387 Below you will find the \\dontdocument command in the
388 dontdocument.qdoc for widgets:
389
390 \badcode *
391 /\1!
392 \dontdocument (QTypeInfo QMetaTypeId)
393 \1/
394 \endcode
395
396 \target inheaderfile-command
397 \section1 \\inheaderfile
398
399 The \\inheaderfile meta-command is used for overriding the include statement
400 generated for a C++ class, namespace, or header file reference documentation.
401
402 By default, QDoc documents a \c {\class SomeClass} to be available with
403 a following include statement:
404
405 \code
406 #include <SomeClass>
407 \endcode
408
409 If the actual include statement differs from the default, this can be
410 documented as
411
412 \badcode
413 \class SomeClass
414 \inheaderfile Tools/SomeClass
415 ...
416 \endcode
417
418 See also \l {class-command}{\\class} and
419 \l {headerfile-command}{\\headerfile}.
420
421
422 \target obsolete-command
423 \section1 \\obsolete
424 The \\obsolete command is superceded by the \\deprecated command.
425
426 This command is kept for backwards compatibility reasons only.
427 It may be removed in a future version of QDoc. Use the \\deprecated
428 command instead.
429
430 See also \l {deprecated-command}{\\deprecated}.
431
432 \target deprecated-command
433 \section1 \\deprecated
434
435 The \\deprecated command is for indicating that a function is being
436 deprecated, and that it should no longer be used in new code. There
437 is no guarantee for how long it will remain in the library.
438
439 The \\deprecated command takes two optional arguments:
440 \list
441 \li A version in square brackets (e.g. [6.2]).
442 \li A string with more information, for example a suggested
443 replacement.
444 \endlist
445
446 When generating the reference documentation for a class, QDoc will
447 create and link to a separate page documenting its deprecated
448 functions. It is good practice to suggest an equivalent function
449 as an alternative.
450
451 \badcode *
452 /\1!
453 \fn MyClass::MyDeprecatedFunction
454 \deprecated [6.2] Use MyNewFunction() instead.
455 \1/
456 \endcode
457
458 \target internal-command
459 \section1 \\internal
460
461 The \\internal command indicates that the referenced
462 function is not part of the public interface.
463
464 The command must stand on its own line.
465
466 QDoc ignores the documentation as well as the documented item,
467 when generating the associated class reference documentation.
468
469 \badcode *
470 /\1!
471 \internal
472
473 Tries to find the decimal separator. If it can't find
474 it and the thousand delimiter is != '.' it will try to
475 find a '.';
476 \1/
477 int QDoubleSpinBoxPrivate::findDelimiter
478 (const QString &str, int index) const
479 {
480 int dotindex = str.indexOf(delimiter, index);
481 if (dotindex == -1 && thousand != dot && delimiter != dot)
482 dotindex = str.indexOf(dot, index);
483 return dotindex;
484 }
485 \endcode
486
487 This function will not be included in the documentation, unless QDoc
488 is called with the \c{-showinternal} command line option or the
489 \c{QDOC_SHOW_INTERNAL} environment variable is set.
490
491 \target modulestate-command
492 \section1 \\modulestate
493
494 Use the \\modulestate command within a \\module or \\qmlmodule
495 topic to provide a custom module state description.
496
497 The command takes an argument that describes the module's
498 state. For example:
499
500 \badcode *
501 /*!
502 \module QtFoo
503 \modulestate Technical Preview
504 \1/
505 \endcode
506
507 QDoc will then add this information on the module page:
508
509 \quotation
510 This module is in \e {Technical Preview} state.
511 \endquotation
512
513 \note Do not use this command to deprecate a module. Use the
514 \l {deprecated-command}{\\deprecated} command instead.
515
516 In HTML output, this state information appears also in the navigation
517 bar (breadcrumbs) of reference pages for the module's members.
518
519 \target preliminary-command
520 \section1 \\preliminary
521
522 The \\preliminary command is for indicating that a referenced
523 function is still under development.
524
525 The command must stand on its own line.
526
527 The \\preliminary command expands to a notification in the
528 function documentation, and marks the function as preliminary when
529 it appears in lists.
530
531 \badcode *
532 /\1!
533 \preliminary
534
535 Returns information about the joining type attributes of the
536 character (needed for certain languages such as Arabic or
537 Syriac).
538
539 \1/
540 QChar::JoiningType QChar::joiningType() const
541 {
542 return QChar::joiningType(ucs);
543 }
544 \endcode
545
546 \target readonly-command
547 \section1 \\readonly
548
549 The \\readonly command is used in conjunction with a \l {qmlproperty-command}
550 {\\qmlproperty} command to mark the QML property as read-only.
551
552 \target required-command
553 \section1 \\required
554
555 The \\required command is used in conjunction with a \l {qmlproperty-command}
556 {\\qmlproperty} command to mark the QML property as required.
557
558 \b {See also} \l {The Property System}.
559
560 \target since-command
561 \section1 \\since
562
563 The \\since command tells in which minor release
564 the associated functionality was added.
565
566 If the argument passed to \\since contains no spaces, it is assumed to be
567 shorthand notation for the \l {productname-variable}{productname}, and QDoc
568 will prefix the version with the value of \c productname in the generated
569 output. If the \c productname variable is undefined, QDoc generates only
570 the version string.
571
572 The argument can also contain the product name explicitly:
573
574 \badcode
575 \since MyFramework 2.0
576 \endcode
577
578 In this case, the arguments (product and version) are used as is.
579
580 \section2 Inheritance of Since Information
581
582 Since QDoc version 6.5, C++ classes and QML types inherit the \\since statement
583 from their respective \l {module-command}{module} or \l {qmlmodule-command}
584 {QML module}, unless \\since is explicitly used in the type documentation.
585
586 \section2 Since Clause
587
588 The \\value command allows an optional \e {since} clause, enclosed in square
589 brackets, to immediately follow the command string. This is used for
590 marking specific C++ enum values with since information.
591
592 See also \l {value-command}{\\value} and \l {ignoresince}.
593
594 \target wrapper-command
595 \section1 \\wrapper
596
597 The \\wrapper command, when used in a C++ class documentation, marks the
598 class as a \e wrapper that provides access to a non-Qt API. This command
599 is used for suppressing warnings that might otherwise be generated for
600 members of such a class.
601*/
602
603
604/*!
605 \page 17-qdoc-commands-thread.html
606 \previouspage Status
607 \nextpage Relating Things
608
609 \title Thread Support
610
611 The thread support commands are for specifying the level of
612 support for multithreaded programming in a class or function.
613 There are three levels of support: \c threadsafe, \c reentrant and
614 \c nonreentrant.
615
616 The default is \c nonreentrant which means that the associated
617 class or function cannot be called by multiple threads. \c
618 Reentrant and \c threadsafe are levels primarily used for classes.
619
620 \c Reentrant means that all the functions in the referenced class
621 can be called simultaneously by multiple threads, provided that
622 each invocation of the functions reference unique data. While \c
623 threadsafe means that all the functions in the referenced class
624 can be called simultaneously by multiple threads even when each
625 invocation references shared data.
626
627 When a class is marked \l {reentrant-command} {\\reentrant} or \l
628 {threadsafe-command} {\\threadsafe}, functions in that class can
629 be marked \c nonreentrant using the \l {nonreentrant-command}
630 {\\nonreentrant} command.
631
632 \section1 Example
633
634 \target reentrant-example
635 \badcode *
636 /\1!
637 \class QLocale
638 \brief The QLocale class converts between numbers and their
639 string representations in various languages.
640
641 \reentrant
642 \ingroup i18n
643 \ingroup text
644
645 QLocale is initialized with a language/country pair in its
646 constructor and offers number-to-string and string-to-number
647 conversion functions similar to those in QString.
648
649 ...
650
651 \nonreentrant
652
653 Sets the global default locale to \a locale. These values are
654 used when a QLocale object is constructed with no
655 arguments. If this function is not called, the system's locale
656 is used.
657
658 \warning In a multithreaded application, the default locale
659 should be set at application startup, before any non-GUI
660 threads are created.
661
662 \sa system(), c()
663 \1/
664 void QLocale::setDefault(const QLocale &locale)
665 {
666 default_d = locale.d;
667 }
668 \endcode
669
670 QDoc generates a notification when a class is
671 declared reentrant, and lists the exceptions (the declared
672 nonreentrant functions). A link to the general documentation on \l
673 {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is
674 included. In addition a warning, "\b Warning: This function is
675 not reentrant.", is generated in the nonreentrant functions'
676 documentation.
677
678 QDoc will generate the same notification and warnings when a class
679 is declared threadsafe.
680
681 For more information see the general documentation on \l
682 {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}.
683
684 \section1 Commands
685
686 \target threadsafe-command
687 \section2 \\threadsafe
688
689 The \\threadsafe command includes a line in the documentation to
690 indicate that the associated class or function is \e threadsafe
691 and can be called simultaneously by multiple threads, even when
692 separate invocations reference shared data.
693
694 The command must stand on its own line.
695
696 The documentation generated from this command will be similar to
697 the what is generated for the \l {reentrant-command} {\\reentrant}
698 command. See the example above in the \l {reentrant-example}
699 {introduction}.
700
701 See also \l{reentrant-command} {\\reentrant} and
702 \l{nonreentrant-command} {\\nonreentrant}.
703
704 \target reentrant-command
705 \section2 \\reentrant
706
707 The \\reentrant command indicates that the associated class or
708 function can be called simultaneously by multiple threads,
709 provided that each invocation references its own data. See the \l
710 {reentrant-example} {example} above.
711
712 The command must stand on its own line.
713
714 See also \l{nonreentrant-command} {\\nonreentrant} and
715 \l{threadsafe-command} {\\threadsafe}.
716
717 \target nonreentrant-command
718 \section2 \\nonreentrant
719
720 The \\nonreentrant command indicates that the associated class or
721 function cannot be called by multiple threads. Nonreentrant is the
722 default case.
723
724 The command must stand on its own line.
725
726 When a class is marked \l {reentrant-command} {\\reentrant} or \l
727 {threadsafe-command} {\\threadsafe}, functions in that class can
728 be marked \c nonreentrant using this command in the \l{fn-command}
729 {\\fn} comment of the functions to be excluded.
730
731 See also \l{reentrant-command} {\\reentrant} and
732 \l{threadsafe-command} {\\threadsafe}.
733*/
734
735/*!
736 \page 18-qdoc-commands-relating.html
737 \previouspage Thread Support
738 \nextpage Grouping Things
739
740 \title Relating Things
741
742 The relating commands are for specifying how one documented
743 element relates to another documented element. Some examples:
744 \list
745 \li This function is an overload of another function.
746 \li This function is a reimplementation of another function.
747 \li This typedef is \e related to some class or header file.
748 \endlist
749
750 There is also a command for documenting that a QML type inherits
751 some other QML type.
752
753 \section1 Commands
754
755 \target inherits-command
756 \section2 \\inherits
757
758 The \\inherits command is for documenting that one QML type
759 inherits some other QML type. It must be included in the
760 inheriting element's \l{qmltype-command}{\\qmltype} comment.
761 The argument is the name of the inherited QML type.
762
763 \badcode *
764 /\1!
765 \qmltype PauseAnimation
766 \nativetype QDeclarativePauseAnimation
767 \ingroup qml-animation-transition
768 \since 4.7
769 \inherits Animation
770 \brief The PauseAnimation element provides a pause for an animation.
771
772 When used in a SequentialAnimation, PauseAnimation is a step
773 when nothing happens, for a specified duration.
774
775 A 500ms animation sequence, with a 100ms pause between two animations:
776
777 SequentialAnimation {
778 NumberAnimation { ... duration: 200 }
779 PauseAnimation { duration: 100 }
780 NumberAnimation { ... duration: 200 }
781 }
782
783 \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
784 \1/
785 \endcode
786
787 QDoc includes this line on the reference page for the
788 \l [QML] PauseAnimation
789 element:
790
791 \quotation
792 Inherits \l [QML] Animation
793 \endquotation
794
795 \target overload-command
796 \section2 \\overload
797
798 The \\overload command is for indicating that a function is a
799 secondary overload of its name. The command must stand on its own
800 line. If the command is used with a function that isn't an actual
801 overload, it's considered a no-op.
802
803 For a function name that is overloaded (except constructors), QDoc
804 expects one primary version of the function, and all the others
805 marked with the \b {\\overload command}. The primary version
806 should be fully documented. Each overload can have whatever extra
807 documentation you want to add for just that overloaded version.
808
809 You can include the function name plus '()' as a parameter to
810 the \b{\\overload} command, which will include a standard
811 \e{This function overloads...} line of text with a link
812 to the documentation for the primary version of the function.
813
814 You can use either a fully qualified name (such as \c{QMenu::addAction()})
815 or an unqualified name (such as \c{addAction()}). When you use an
816 unqualified function name, QDoc automatically qualifies it by using the
817 parent class or namespace name. For example, \c{addAction()} becomes
818 \c{QMenu::addAction()} when used within the \c{QMenu} class documentation.
819
820 For parameterless targets like \c{\\overload functionName()}, QDoc searches
821 for a link target in this order:
822 \list 1
823 \li The function explicitly marked with \c{\\overload primary}, if one
824 exists.
825 \li The parameterless overload of that function, if one exists.
826 \li The overload QDoc determines to be primary based on its sorting
827 rules.
828 \endlist
829
830 QDoc automatically determines the primary overload by prioritizing functions
831 that are: non-internal, then non-overload (no \c{\\overload} command), then
832 documented, then by lexicographic comparison (alphabetical ordering of
833 function signatures). To override this automatic selection and explicitly
834 designate which overload should be the primary target, use
835 \c{\\overload primary} on that function.
836
837 \note If multiple functions are marked with \c{\\overload primary}, QDoc
838 will issue a warning and determine the primary overload using lexicographic
839 comparison among the competing primary candidates.
840
841 \badcode *
842 /\1!
843 \overload addAction()
844
845 This convenience function creates a new action with an
846 \a icon and some \a text. The function adds the newly
847 created action to the menu's list of actions, and
848 returns it.
849
850 \sa QWidget::addAction()
851 \1/
852 QAction *QMenu::addAction(const QIcon &icon, const QString &text)
853 {
854 QAction *ret = new QAction(icon, text, this);
855 addAction(ret);
856 return ret;
857 }
858 \endcode
859
860 If you don't include the function name with the \b{\\overload}
861 command, then instead of the "This function overloads..." line
862 with the link to the documentation for the primary version, you
863 get the old standard line:
864
865 \quotation
866 This is an overloaded member function, provided for
867 convenience.
868 \endquotation.
869
870 \target reimp-command
871 \section2 \\reimp
872
873 The \\reimp command is for indicating that a function is a
874 reimplementation of a virtual function without requiring any
875 additional documentation.
876
877 By default, QDoc will omit a reimplemented virtual function from the
878 class reference unless it is documented. This command ensures that an
879 otherwise undocumented function will be included.
880
881 The command must stand on its own line.
882
883 \badcode *
884 /\1!
885 \reimp
886 \1/
887 void QToolButton::nextCheckState()
888 {
889 Q_D(QToolButton);
890 if (!d->defaultAction)
891 QAbstractButton::nextCheckState();
892 else
893 d->defaultAction->trigger();
894 }
895 \endcode
896
897 This function will not be included in the documentation. Instead,
898 a link to the base function QAbstractButton::nextCheckState() will
899 appear in the documentation.
900
901 \target relates-command
902 \section2 \\relates
903
904 The \\relates command is for including the documentation of an
905 entity (a function, macro, typedef, enum, or variable) to a class,
906 namespace, or header file. The argument is the name of the class,
907 namespace, or header the entity is related to.
908
909 If the argument refers to a templated type, use the type name only
910 (without template parameters).
911
912 \badcode *
913 /\1!
914 \relates QChar
915
916 Reads a char from the stream \a in into char \a chr.
917
918 \sa {Format of the QDataStream operators}
919 \1/
920 QDataStream &operator>>(QDataStream &in, QChar &chr)
921 {
922 quint16 u;
923 in >> u;
924 chr.unicode() = ushort(u);
925 return in;
926 }
927 \endcode
928
929 The documentation for this function is included on the reference
930 page for class QChar, listed under the \e {Related Non-members} section.
931*/
932
933/*!
934 \page 19-qdoc-commands-grouping.html
935 \previouspage Relating Things
936 \nextpage Naming Things
937
938 \title Grouping Things
939
940 The grouping commands relate classes to defined groups and
941 modules. The groups are used when generating lists of related
942 classes in the documentation, while the modules are elements of
943 Qt's structure.
944
945 \section1 Commands
946
947 \target ingroup-command
948 \section2 \\ingroup
949
950 The \\ingroup command indicates that the given
951 class, page, or other entity belongs to a certain group of
952 related documentation.
953
954 An entity may belong to multiple groups.
955
956 The \\ingroup command's argument is a group name, but note
957 that the command considers the rest of the line as part of
958 its argument. Make sure that the group name is followed by
959 a linebreak.
960
961 \badcode *
962 /\1!
963 \class QDir
964 \brief The QDir class provides access to directory
965 structures and their contents.
966
967 \ingroup io
968 ...
969 \1/
970 \endcode
971
972 This adds the QDir class to the \c io group. An entry for QDir
973 will then appear on the list created with, for example,
974 the \l {annotatedlist-command} {\\annotatedlist} command with
975 an argument \c io.
976
977 QDoc automatically generates links to associated groups on a
978 C++ class, namespace, or header reference page. For example,
979 given the above documentation for class \QDir and the following
980 \l {group-command}{\\group} page:
981
982 \badcode *
983 /\1
984 \group io
985 \title Input/Output and Networking
986 ...
987 \1/
988 \endcode
989
990 QDoc then outputs a statement on the QDir reference page:
991
992 \quotation
993 \list
994 \li \QDir is part of \l {Input/Output and Networking}.
995 \endlist
996 \endquotation
997
998 For HTML output, QDoc also generates a link to the group
999 page as part of the navigation bar (breadcrumbs). If multiple
1000 \\ingroup commands are used, the first one that references
1001 a documented \\group is selected.
1002
1003 See also \l {group-command} {\\group}.
1004
1005 \target inmodule-command
1006 \section2 \\inmodule
1007
1008 The \\inmodule command relates a class to the module specified by
1009 the command's argument.
1010
1011 For the basic classes in Qt, a class's module is determined by its
1012 location, namely its directory. However, for extensions like
1013 ActiveQt and \QD, a class must be related to a module
1014 explicitly.
1015
1016 The command's argument is a module name, but note that the command
1017 considers the rest of the line as part of its argument. Make sure
1018 that the module name is followed by a linebreak.
1019
1020 \code
1021 /*!
1022 \class QDesignerTaskMenuExtension
1023 \inmodule QtDesigner
1024 * /
1025 \endcode
1026
1027 This ensures that the QDesignerTaskMenuExtension class is included
1028 in the \QD module, which means, for example, that the
1029 class will appear on the list created by calling the \l
1030 {generatelist-command} {\\generatelist} command with the \c
1031 {{classesbymodule QtDesigner}} argument.
1032
1033 See also \l {module-command} {\\module} and \l
1034 {generatelist-command} {\\generatelist}.
1035*/
1036
1037/*!
1038 \page 20-qdoc-commands-namingthings.html
1039 \previouspage Grouping Things
1040 \nextpage Markup Commands
1041
1042 \title Naming Things
1043
1044 In general, a title command considers everything that follows it
1045 until the first line break as its argument. If the title is so
1046 long it must span multiple lines, end each line (except the last
1047 one) with a backslash.
1048
1049 \section1 Commands
1050
1051 \target title-command
1052 \section2 \\title
1053
1054 The \\title command sets the title for a documentation page, or
1055 allows you to override it.
1056
1057 \badcode *
1058 /\1!
1059 \page signalandslots.html
1060
1061 \title Signals & Slots
1062
1063 Signals and slots are used for communication between
1064 objects. The signals and slots mechanism is a central
1065 feature of Qt, and probably the part that differs most
1066 from the features provided by other frameworks.
1067
1068 ...
1069 \1/
1070 \endcode
1071
1072 See also \l {subtitle-command} {\\subtitle}.
1073
1074 \target subtitle-command
1075 \section2 \\subtitle
1076
1077 The \\subtitle command sets a subtitle for a documentation page.
1078
1079 \badcode *
1080 /\1!
1081 \page qtopiacore-overview.html
1082
1083 \title Qtopia Core
1084 \subtitle Qt for Embedded Linux
1085
1086 Qt/Embedded, the embedded Linux port of Qt, is a
1087 complete and self-contained C++ GUI and platform
1088 development tool for Linux-based embedded development.
1089 ...
1090 \1/
1091 \endcode
1092
1093 See also \l {title-command} {\\title}.
1094
1095*/