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