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