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 the associated element
436 is deprecated, and that it should no longer be used in new code.
437
438 The \\deprecated command takes two optional arguments:
439 \list
440 \li A version in square brackets (e.g. [6.2]).
441 \li A string with more information, for example a suggested
442 replacement.
443 \endlist
444
445 When generating the reference documentation for a class, QDoc
446 creates and links to a separate page that documents deprecated members.
447 It's good practice to suggest an equivalent alternative.
448
449 \badcode *
450 /\1!
451 \fn MyClass::MyDeprecatedFunction
452 \deprecated [6.2] Use MyNewFunction() instead.
453 \1/
454 \endcode
455
456 \target internal-command
457 \section1 \\internal
458
459 The \\internal command indicates that the documented element
460 is not part of the public interface.
461
462 The command must stand on its own line.
463
464 QDoc ignores the documentation as well as the documented item,
465 when generating the associated class reference documentation.
466
467 \badcode *
468 /\1!
469 \internal
470
471 Tries to find the decimal separator. If it can't find
472 it and the thousand delimiter is != '.' it will try to
473 find a '.';
474 \1/
475 int QDoubleSpinBoxPrivate::findDelimiter
476 (const QString &str, int index) const
477 {
478 int dotindex = str.indexOf(delimiter, index);
479 if (dotindex == -1 && thousand != dot && delimiter != dot)
480 dotindex = str.indexOf(dot, index);
481 return dotindex;
482 }
483 \endcode
484
485 This function will not be included in the documentation, unless QDoc
486 is called with the \c{-showinternal} command line option or the
487 \c{QDOC_SHOW_INTERNAL} environment variable is set.
488
489 \target modulestate-command
490 \section1 \\modulestate
491
492 Use the \\modulestate command within a \\module or \\qmlmodule
493 topic to provide a custom module state description.
494
495 The command takes an argument that describes the module's
496 state. For example:
497
498 \badcode *
499 /*!
500 \module QtFoo
501 \modulestate Technology Preview
502 \1/
503 \endcode
504
505 QDoc will then add this information on the module page:
506
507 \quotation
508 This module is in \e {Technology Preview} state.
509 \endquotation
510
511 \note Do not use this command to deprecate a module. Use the
512 \l {deprecated-command}{\\deprecated} command instead.
513
514 In HTML output, this state information appears also in the navigation
515 bar (breadcrumbs) of reference pages for the module's members.
516
517 \target preliminary-command
518 \section1 \\preliminary
519
520 The \\preliminary command is for indicating that the documented
521 element is still under development.
522
523 The command must stand on its own line.
524
525 The \\preliminary command expands to a note in the
526 documentation, and marks the element as preliminary when it appears
527 in lists.
528
529 \badcode *
530 /\1!
531 \preliminary
532
533 Returns information about the joining type attributes of the
534 character (needed for certain languages such as Arabic or
535 Syriac).
536
537 \1/
538 QChar::JoiningType QChar::joiningType() const
539 {
540 return QChar::joiningType(ucs);
541 }
542 \endcode
543
544 Since QDoc version 6.12, it is possible to customize the status
545 descriptor and the contents of the generated note for elements
546 marked with \\preliminary.
547
548 See also \qdocvar {preliminary} configuration variable.
549
550 \target readonly-command
551 \section1 \\readonly
552
553 The \\readonly command is used in conjunction with a \l {qmlproperty-command}
554 {\\qmlproperty} command to mark the QML property as read-only.
555
556 \target required-command
557 \section1 \\required
558
559 The \\required command is used in conjunction with a \l {qmlproperty-command}
560 {\\qmlproperty} command to mark the QML property as required.
561
562 \b {See also} \l {The Property System}.
563
564 \target since-command
565 \section1 \\since
566
567 The \\since command tells in which minor release
568 the associated functionality was added.
569
570 If the argument passed to \\since contains no spaces, it is assumed to be
571 shorthand notation for the \l {productname-variable}{productname}, and QDoc
572 will prefix the version with the value of \c productname in the generated
573 output. If the \c productname variable is undefined, QDoc generates only
574 the version string.
575
576 The argument can also contain the product name explicitly:
577
578 \badcode
579 \since MyFramework 2.0
580 \endcode
581
582 In this case, the arguments (product and version) are used as is.
583
584 \section2 Inheritance of Since Information
585
586 Since QDoc version 6.5, C++ classes and QML types inherit the \\since statement
587 from their respective \l {module-command}{module} or \l {qmlmodule-command}
588 {QML module}, unless \\since is explicitly used in the type documentation.
589
590 \section2 Since Clause
591
592 The \\value command allows an optional \e {since} clause, enclosed in square
593 brackets, to immediately follow the command string. This is used for
594 marking specific C++ enum values with since information.
595
596 See also \l {value-command}{\\value} and \l {ignoresince}.
597
598 \target wrapper-command
599 \section1 \\wrapper
600
601 The \\wrapper command, when used in a C++ class documentation, marks the
602 class as a \e wrapper that provides access to a non-Qt API. This command
603 is used for suppressing warnings that might otherwise be generated for
604 members of such a class.
605*/
606
607
608/*!
609 \page 17-qdoc-commands-thread.html
610 \previouspage Status
611 \nextpage Relating Things
612
613 \title Thread Support
614
615 The thread support commands are for specifying the level of
616 support for multithreaded programming in a class or function.
617 There are three levels of support: \c threadsafe, \c reentrant and
618 \c nonreentrant.
619
620 The default is \c nonreentrant which means that the associated
621 class or function cannot be called by multiple threads. \c
622 Reentrant and \c threadsafe are levels primarily used for classes.
623
624 \c Reentrant means that all the functions in the referenced class
625 can be called simultaneously by multiple threads, provided that
626 each invocation of the functions reference unique data. While \c
627 threadsafe means that all the functions in the referenced class
628 can be called simultaneously by multiple threads even when each
629 invocation references shared data.
630
631 When a class is marked \l {reentrant-command} {\\reentrant} or \l
632 {threadsafe-command} {\\threadsafe}, functions in that class can
633 be marked \c nonreentrant using the \l {nonreentrant-command}
634 {\\nonreentrant} command.
635
636 \section1 Example
637
638 \target reentrant-example
639 \badcode *
640 /\1!
641 \class QLocale
642 \brief The QLocale class converts between numbers and their
643 string representations in various languages.
644
645 \reentrant
646 \ingroup i18n
647 \ingroup text
648
649 QLocale is initialized with a language/country pair in its
650 constructor and offers number-to-string and string-to-number
651 conversion functions similar to those in QString.
652
653 ...
654
655 \nonreentrant
656
657 Sets the global default locale to \a locale. These values are
658 used when a QLocale object is constructed with no
659 arguments. If this function is not called, the system's locale
660 is used.
661
662 \warning In a multithreaded application, the default locale
663 should be set at application startup, before any non-GUI
664 threads are created.
665
666 \sa system(), c()
667 \1/
668 void QLocale::setDefault(const QLocale &locale)
669 {
670 default_d = locale.d;
671 }
672 \endcode
673
674 QDoc generates a notification when a class is
675 declared reentrant, and lists the exceptions (the declared
676 nonreentrant functions). A link to the general documentation on \l
677 {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is
678 included. In addition a warning, "\b Warning: This function is
679 not reentrant.", is generated in the nonreentrant functions'
680 documentation.
681
682 QDoc will generate the same notification and warnings when a class
683 is declared threadsafe.
684
685 For more information see the general documentation on \l
686 {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}.
687
688 \section1 Commands
689
690 \target threadsafe-command
691 \section2 \\threadsafe
692
693 The \\threadsafe command includes a line in the documentation to
694 indicate that the associated class or function is \e threadsafe
695 and can be called simultaneously by multiple threads, even when
696 separate invocations reference shared data.
697
698 The command must stand on its own line.
699
700 The documentation generated from this command will be similar to
701 the what is generated for the \l {reentrant-command} {\\reentrant}
702 command. See the example above in the \l {reentrant-example}
703 {introduction}.
704
705 See also \l{reentrant-command} {\\reentrant} and
706 \l{nonreentrant-command} {\\nonreentrant}.
707
708 \target reentrant-command
709 \section2 \\reentrant
710
711 The \\reentrant command indicates that the associated class or
712 function can be called simultaneously by multiple threads,
713 provided that each invocation references its own data. See the \l
714 {reentrant-example} {example} above.
715
716 The command must stand on its own line.
717
718 See also \l{nonreentrant-command} {\\nonreentrant} and
719 \l{threadsafe-command} {\\threadsafe}.
720
721 \target nonreentrant-command
722 \section2 \\nonreentrant
723
724 The \\nonreentrant command indicates that the associated class or
725 function cannot be called by multiple threads. Nonreentrant is the
726 default case.
727
728 The command must stand on its own line.
729
730 When a class is marked \l {reentrant-command} {\\reentrant} or \l
731 {threadsafe-command} {\\threadsafe}, functions in that class can
732 be marked \c nonreentrant using this command in the \l{fn-command}
733 {\\fn} comment of the functions to be excluded.
734
735 See also \l{reentrant-command} {\\reentrant} and
736 \l{threadsafe-command} {\\threadsafe}.
737*/
738
739/*!
740 \page 18-qdoc-commands-relating.html
741 \previouspage Thread Support
742 \nextpage Grouping Things
743
744 \title Relating Things
745
746 The relating commands are for specifying how one documented
747 element relates to another documented element. Some examples:
748 \list
749 \li This function is an overload of another function.
750 \li This function is a reimplementation of another function.
751 \li This typedef is \e related to some class or header file.
752 \endlist
753
754 There is also a command for documenting that a QML type inherits
755 some other QML type.
756
757 \section1 Commands
758
759 \target inherits-command
760 \section2 \\inherits
761
762 The \\inherits command is for documenting that one QML type
763 inherits some other QML type. It must be included in the
764 inheriting element's \l{qmltype-command}{\\qmltype} comment.
765 The argument is the name of the inherited QML type,
766 optionally qualified with a QML module name.
767
768 \badcode *
769 /\1!
770 \qmltype PauseAnimation
771 \inqmlmodule QtQuick
772 \nativetype QDeclarativePauseAnimation
773 \ingroup qml-animation-transition
774 \since 4.7
775 \inherits Animation
776 \brief The PauseAnimation element provides a pause for an animation.
777
778 When used in a SequentialAnimation, PauseAnimation is a step
779 when nothing happens, for a specified duration.
780
781 A 500ms animation sequence, with a 100ms pause between two animations:
782
783 SequentialAnimation {
784 NumberAnimation { ... duration: 200 }
785 PauseAnimation { duration: 100 }
786 NumberAnimation { ... duration: 200 }
787 }
788
789 \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
790 \1/
791 \endcode
792
793 QDoc includes this line on the reference page for the
794 \l [QML] PauseAnimation
795 element:
796
797 \quotation
798 Inherits \l [QML] Animation
799 \endquotation
800
801 When documenting a QML types directly in a .qml file, the \\inherits command
802 is normally not required as QDoc can detect the base type from QML syntax.
803 If present, an \\inherits command will override this automatic base type
804 detection.
805
806 \target overload-command
807 \section2 \\overload
808
809 Use the \e {\\overload} command to mark C++ function overloads. This command
810 must appear on its own line in the documentation comment.
811
812 \section3 How it works
813
814 When you have multiple C++ functions with the same name (overloads) that
815 perform similar work with different parameters, use \e {\\overload} to avoid
816 repetitive documentation. Functions without \e {\\overload} require complete
817 documentation. Functions with \e {\\overload} can focus on their specific
818 differences.
819
820 Functions marked with \e {\\overload} automatically suppress missing
821 parameter warnings, since they reference the documentation of the main
822 function.
823
824 \section3 Basic usage
825
826 \badcode *
827 /\1!
828 \overload
829 Brief description of what makes this overload different.
830 \1/
831 \endcode
832
833 \section3 Linking to the primary function
834
835 Add the function name to create a link to the primary function:
836
837 \badcode *
838 /\1!
839 \overload functionName()
840 Brief description of what makes this overload different.
841 \1/
842 \endcode
843
844 Use either qualified names (\c{ClassName::functionName()}) or unqualified
845 names (\c{functionName()}). QDoc automatically qualifies unqualified names
846 using the current class or namespace.
847
848 \note For historic reasons, a parameterless unqualified name like
849 \c {functionName()} serves as shorthand for linking to the primary overload,
850 not necessarily the parameterless overload. QDoc uses a search algorithm to
851 find the "best" overload to link to. To link to a specific parameterless
852 function, either designate it as the primary overload with
853 \c {\overload primary}, or use a fully qualified signature that explicitly
854 specifies the empty parameter list.
855
856 \section3 Designating a primary overload
857
858 By default, QDoc chooses the primary overload automatically. To explicitly
859 designate which overload serves as the primary, use:
860
861 \badcode *
862 /\1!
863 \overload primary
864 Main documentation for this function family.
865 Document all parameters here.
866 \1/
867 \endcode
868
869 Primary overloads:
870 \list
871 \li Contain the main function documentation.
872 \li Require complete parameter documentation.
873 \li Do not display "This function overloads..." text.
874 \li Serve as the link target for other overloads.
875 \endlist
876
877 Use \e {\\overload primary} when the most important overload differs from
878 QDoc's automatic selection, or when you need consistent linking behavior.
879
880 \target reimp-command
881 \section2 \\reimp
882
883 The \\reimp command is for indicating that a function is a
884 reimplementation of a virtual function without requiring any
885 additional documentation.
886
887 By default, QDoc will omit a reimplemented virtual function from the
888 class reference unless it is documented. This command ensures that an
889 otherwise undocumented function will be included.
890
891 The command must stand on its own line.
892
893 \badcode *
894 /\1!
895 \reimp
896 \1/
897 void QToolButton::nextCheckState()
898 {
899 Q_D(QToolButton);
900 if (!d->defaultAction)
901 QAbstractButton::nextCheckState();
902 else
903 d->defaultAction->trigger();
904 }
905 \endcode
906
907 This function will not be included in the documentation. Instead,
908 a link to the base function QAbstractButton::nextCheckState() will
909 appear in the documentation.
910
911 \target relates-command
912 \section2 \\relates
913
914 The \\relates command is for including the documentation of an
915 entity (a function, macro, typedef, enum, or variable) to a class,
916 namespace, or header file. The argument is the name of the class,
917 namespace, or header the entity is related to.
918
919 If the argument refers to a templated type, use the type name only
920 (without template parameters).
921
922 \badcode *
923 /\1!
924 \relates QChar
925
926 Reads a char from the stream \a in into char \a chr.
927
928 \sa {Format of the QDataStream operators}
929 \1/
930 QDataStream &operator>>(QDataStream &in, QChar &chr)
931 {
932 quint16 u;
933 in >> u;
934 chr.unicode() = ushort(u);
935 return in;
936 }
937 \endcode
938
939 The documentation for this function is included on the reference
940 page for class QChar, listed under the \e {Related Non-members} section.
941*/
942
943/*!
944 \page 19-qdoc-commands-grouping.html
945 \previouspage Relating Things
946 \nextpage Naming Things
947
948 \title Grouping Things
949
950 The grouping commands relate classes to defined groups and
951 modules. The groups are used when generating lists of related
952 classes in the documentation, while the modules are elements of
953 Qt's structure.
954
955 \section1 Commands
956
957 \target ingroup-command
958 \section2 \\ingroup
959
960 The \\ingroup command indicates that the given
961 class, page, or other entity belongs to a certain group of
962 related documentation.
963
964 An entity may belong to multiple groups.
965
966 The \\ingroup command's argument is a group name, but note
967 that the command considers the rest of the line as part of
968 its argument. Make sure that the group name is followed by
969 a linebreak.
970
971 \badcode *
972 /\1!
973 \class QDir
974 \brief The QDir class provides access to directory
975 structures and their contents.
976
977 \ingroup io
978 ...
979 \1/
980 \endcode
981
982 This adds the QDir class to the \c io group. An entry for QDir
983 will then appear on the list created with, for example,
984 the \l {annotatedlist-command} {\\annotatedlist} command with
985 an argument \c io.
986
987 QDoc automatically generates links to associated groups on a
988 C++ class, namespace, or header reference page. For example,
989 given the above documentation for class \QDir and the following
990 \l {group-command}{\\group} page:
991
992 \badcode *
993 /\1
994 \group io
995 \title Input/Output and Networking
996 ...
997 \1/
998 \endcode
999
1000 QDoc then outputs a statement on the QDir reference page:
1001
1002 \quotation
1003 \list
1004 \li \QDir is part of \l {Input/Output and Networking}.
1005 \endlist
1006 \endquotation
1007
1008 For HTML output, QDoc also generates a link to the group
1009 page as part of the navigation bar (breadcrumbs). If multiple
1010 \\ingroup commands are used, the first one that references
1011 a documented \\group is selected.
1012
1013 See also \l {group-command} {\\group}.
1014
1015 \target inmodule-command
1016 \section2 \\inmodule
1017
1018 The \\inmodule command relates a class to the module specified by
1019 the command's argument.
1020
1021 For the basic classes in Qt, a class's module is determined by its
1022 location, namely its directory. However, for extensions like
1023 ActiveQt and \QD, a class must be related to a module
1024 explicitly.
1025
1026 The command's argument is a module name, but note that the command
1027 considers the rest of the line as part of its argument. Make sure
1028 that the module name is followed by a linebreak.
1029
1030 \code
1031 /*!
1032 \class QDesignerTaskMenuExtension
1033 \inmodule QtDesigner
1034 * /
1035 \endcode
1036
1037 This ensures that the QDesignerTaskMenuExtension class is included
1038 in the \QD module, which means, for example, that the
1039 class will appear on the list created by calling the \l
1040 {generatelist-command} {\\generatelist} command with the \c
1041 {{classesbymodule QtDesigner}} argument.
1042
1043 See also \l {module-command} {\\module} and \l
1044 {generatelist-command} {\\generatelist}.
1045*/
1046
1047/*!
1048 \page 20-qdoc-commands-namingthings.html
1049 \previouspage Grouping Things
1050 \nextpage Markup Commands
1051
1052 \title Naming Things
1053
1054 In general, a title command considers everything that follows it
1055 until the first line break as its argument. If the title is so
1056 long it must span multiple lines, end each line (except the last
1057 one) with a backslash.
1058
1059 \section1 Commands
1060
1061 \target title-command
1062 \section2 \\title
1063
1064 The \\title command sets the title for a documentation page, or
1065 allows you to override it.
1066
1067 \badcode *
1068 /\1!
1069 \page signalandslots.html
1070
1071 \title Signals & Slots
1072
1073 Signals and slots are used for communication between
1074 objects. The signals and slots mechanism is a central
1075 feature of Qt, and probably the part that differs most
1076 from the features provided by other frameworks.
1077
1078 ...
1079 \1/
1080 \endcode
1081
1082 See also \l {subtitle-command} {\\subtitle}.
1083
1084 \target subtitle-command
1085 \section2 \\subtitle
1086
1087 The \\subtitle command sets a subtitle for a documentation page.
1088
1089 \badcode *
1090 /\1!
1091 \page qtopiacore-overview.html
1092
1093 \title Qtopia Core
1094 \subtitle Qt for Embedded Linux
1095
1096 Qt/Embedded, the embedded Linux port of Qt, is a
1097 complete and self-contained C++ GUI and platform
1098 development tool for Linux-based embedded development.
1099 ...
1100 \1/
1101 \endcode
1102
1103 See also \l {title-command} {\\title}.
1104
1105*/