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 Use the \e {\\overload} command to mark C++ function overloads. This command
799 must appear on its own line in the documentation comment.
800
801 \section3 How it works
802
803 When you have multiple C++ functions with the same name (overloads) that
804 perform similar work with different parameters, use \e {\\overload} to avoid
805 repetitive documentation. Functions without \e {\\overload} require complete
806 documentation. Functions with \e {\\overload} can focus on their specific
807 differences.
808
809 Functions marked with \e {\\overload} automatically suppress missing
810 parameter warnings, since they reference the documentation of the main
811 function.
812
813 \section3 Basic usage
814
815 \badcode *
816 /\1!
817 \overload
818 Brief description of what makes this overload different.
819 \1/
820 \endcode
821
822 \section3 Linking to the primary function
823
824 Add the function name to create a link to the primary function:
825
826 \badcode *
827 /\1!
828 \overload functionName()
829 Brief description of what makes this overload different.
830 \1/
831 \endcode
832
833 Use either qualified names (\c{ClassName::functionName()}) or unqualified
834 names (\c{functionName()}). QDoc automatically qualifies unqualified names
835 using the current class or namespace.
836
837 \note For historic reasons, a parameterless unqualified name like
838 \c {functionName()} serves as shorthand for linking to the primary overload,
839 not necessarily the parameterless overload. QDoc uses a search algorithm to
840 find the "best" overload to link to. To link to a specific parameterless
841 function, either designate it as the primary overload with
842 \c {\overload primary}, or use a fully qualified signature that explicitly
843 specifies the empty parameter list.
844
845 \section3 Designating a primary overload
846
847 By default, QDoc chooses the primary overload automatically. To explicitly
848 designate which overload serves as the primary, use:
849
850 \badcode *
851 /\1!
852 \overload primary
853 Main documentation for this function family.
854 Document all parameters here.
855 \1/
856 \endcode
857
858 Primary overloads:
859 \list
860 \li Contain the main function documentation.
861 \li Require complete parameter documentation.
862 \li Do not display "This function overloads..." text.
863 \li Serve as the link target for other overloads.
864 \endlist
865
866 Use \e {\\overload primary} when the most important overload differs from
867 QDoc's automatic selection, or when you need consistent linking behavior.
868
869 \target reimp-command
870 \section2 \\reimp
871
872 The \\reimp command is for indicating that a function is a
873 reimplementation of a virtual function without requiring any
874 additional documentation.
875
876 By default, QDoc will omit a reimplemented virtual function from the
877 class reference unless it is documented. This command ensures that an
878 otherwise undocumented function will be included.
879
880 The command must stand on its own line.
881
882 \badcode *
883 /\1!
884 \reimp
885 \1/
886 void QToolButton::nextCheckState()
887 {
888 Q_D(QToolButton);
889 if (!d->defaultAction)
890 QAbstractButton::nextCheckState();
891 else
892 d->defaultAction->trigger();
893 }
894 \endcode
895
896 This function will not be included in the documentation. Instead,
897 a link to the base function QAbstractButton::nextCheckState() will
898 appear in the documentation.
899
900 \target relates-command
901 \section2 \\relates
902
903 The \\relates command is for including the documentation of an
904 entity (a function, macro, typedef, enum, or variable) to a class,
905 namespace, or header file. The argument is the name of the class,
906 namespace, or header the entity is related to.
907
908 If the argument refers to a templated type, use the type name only
909 (without template parameters).
910
911 \badcode *
912 /\1!
913 \relates QChar
914
915 Reads a char from the stream \a in into char \a chr.
916
917 \sa {Format of the QDataStream operators}
918 \1/
919 QDataStream &operator>>(QDataStream &in, QChar &chr)
920 {
921 quint16 u;
922 in >> u;
923 chr.unicode() = ushort(u);
924 return in;
925 }
926 \endcode
927
928 The documentation for this function is included on the reference
929 page for class QChar, listed under the \e {Related Non-members} section.
930*/
931
932/*!
933 \page 19-qdoc-commands-grouping.html
934 \previouspage Relating Things
935 \nextpage Naming Things
936
937 \title Grouping Things
938
939 The grouping commands relate classes to defined groups and
940 modules. The groups are used when generating lists of related
941 classes in the documentation, while the modules are elements of
942 Qt's structure.
943
944 \section1 Commands
945
946 \target ingroup-command
947 \section2 \\ingroup
948
949 The \\ingroup command indicates that the given
950 class, page, or other entity belongs to a certain group of
951 related documentation.
952
953 An entity may belong to multiple groups.
954
955 The \\ingroup command's argument is a group name, but note
956 that the command considers the rest of the line as part of
957 its argument. Make sure that the group name is followed by
958 a linebreak.
959
960 \badcode *
961 /\1!
962 \class QDir
963 \brief The QDir class provides access to directory
964 structures and their contents.
965
966 \ingroup io
967 ...
968 \1/
969 \endcode
970
971 This adds the QDir class to the \c io group. An entry for QDir
972 will then appear on the list created with, for example,
973 the \l {annotatedlist-command} {\\annotatedlist} command with
974 an argument \c io.
975
976 QDoc automatically generates links to associated groups on a
977 C++ class, namespace, or header reference page. For example,
978 given the above documentation for class \QDir and the following
979 \l {group-command}{\\group} page:
980
981 \badcode *
982 /\1
983 \group io
984 \title Input/Output and Networking
985 ...
986 \1/
987 \endcode
988
989 QDoc then outputs a statement on the QDir reference page:
990
991 \quotation
992 \list
993 \li \QDir is part of \l {Input/Output and Networking}.
994 \endlist
995 \endquotation
996
997 For HTML output, QDoc also generates a link to the group
998 page as part of the navigation bar (breadcrumbs). If multiple
999 \\ingroup commands are used, the first one that references
1000 a documented \\group is selected.
1001
1002 See also \l {group-command} {\\group}.
1003
1004 \target inmodule-command
1005 \section2 \\inmodule
1006
1007 The \\inmodule command relates a class to the module specified by
1008 the command's argument.
1009
1010 For the basic classes in Qt, a class's module is determined by its
1011 location, namely its directory. However, for extensions like
1012 ActiveQt and \QD, a class must be related to a module
1013 explicitly.
1014
1015 The command's argument is a module name, but note that the command
1016 considers the rest of the line as part of its argument. Make sure
1017 that the module name is followed by a linebreak.
1018
1019 \code
1020 /*!
1021 \class QDesignerTaskMenuExtension
1022 \inmodule QtDesigner
1023 * /
1024 \endcode
1025
1026 This ensures that the QDesignerTaskMenuExtension class is included
1027 in the \QD module, which means, for example, that the
1028 class will appear on the list created by calling the \l
1029 {generatelist-command} {\\generatelist} command with the \c
1030 {{classesbymodule QtDesigner}} argument.
1031
1032 See also \l {module-command} {\\module} and \l
1033 {generatelist-command} {\\generatelist}.
1034*/
1035
1036/*!
1037 \page 20-qdoc-commands-namingthings.html
1038 \previouspage Grouping Things
1039 \nextpage Markup Commands
1040
1041 \title Naming Things
1042
1043 In general, a title command considers everything that follows it
1044 until the first line break as its argument. If the title is so
1045 long it must span multiple lines, end each line (except the last
1046 one) with a backslash.
1047
1048 \section1 Commands
1049
1050 \target title-command
1051 \section2 \\title
1052
1053 The \\title command sets the title for a documentation page, or
1054 allows you to override it.
1055
1056 \badcode *
1057 /\1!
1058 \page signalandslots.html
1059
1060 \title Signals & Slots
1061
1062 Signals and slots are used for communication between
1063 objects. The signals and slots mechanism is a central
1064 feature of Qt, and probably the part that differs most
1065 from the features provided by other frameworks.
1066
1067 ...
1068 \1/
1069 \endcode
1070
1071 See also \l {subtitle-command} {\\subtitle}.
1072
1073 \target subtitle-command
1074 \section2 \\subtitle
1075
1076 The \\subtitle command sets a subtitle for a documentation page.
1077
1078 \badcode *
1079 /\1!
1080 \page qtopiacore-overview.html
1081
1082 \title Qtopia Core
1083 \subtitle Qt for Embedded Linux
1084
1085 Qt/Embedded, the embedded Linux port of Qt, is a
1086 complete and self-contained C++ GUI and platform
1087 development tool for Linux-based embedded development.
1088 ...
1089 \1/
1090 \endcode
1091
1092 See also \l {title-command} {\\title}.
1093
1094*/