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