Prints a warning message containing the source code
file name and line number if \a test is false.
...
\sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
* /
\endcode
\quotation
\raw HTML
void Q_ASSERT ( bool test )
\endraw
Prints a warning message containing the source code
file name and line number if \a test is false.
...
See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}.
\endquotation
\code
/ *!
\macro Q_PROPERTY(...)
\relates QObject
This macro declares a QObject property. The syntax is:
...
\sa {Qt's Property System}
* /
\endcode
\quotation
\raw HTML
Q_PROPERTY ( ... )
\endraw
This macro declares a QObject property. The syntax is:
...
See also \l {Qt's Property System}.
\endquotation
\code
/ *!
\macro Q_OBJECT
\relates QObject
The Q_OBJECT macro must appear in the private section
of a class definition that declares its own signals and
slots, or that uses other services provided by Qt's
meta-object system.
...
\sa {Meta-Object System}, {Signals and Slots}, {Qt's
Property System}
* /
\endcode
\quotation
\raw HTML
Q_OBJECT
\endraw
The Q_OBJECT macro must appear in the private section
of a class definition that declares its own signals and
slots or that uses other services provided by Qt's
meta-object system.
...
See also \l {Meta-Object System}, \l {Signals &
Slots} and \l {Qt's Property System}.
\endquotation
\target module-command
\section1 \\module
The \\module creates a page that lists the classes belonging to
the module specified by the command's argument. A class included
in the module by including the \l {inmodule-command} {\\inmodule}
command in the \\class comment.
The \\module command is typically followed by a \l {title-command}
{\\title} and a \l {brief-command} {\\brief} command. Each class
is listed as a link to the class reference page followed by the
text from the class's \l {brief-command} {\\brief} command. For
example:
\code
/ *!
\module QtNetwork
\title Qt Network Module
\brief Contains classes for writing TCP/IP clients and servers.
The network module provides classes to make network
programming easier and portable. It offers both
high-level classes such as QNetworkAccessManager that
implements application-level protocols, and
lower-level classes such as QTcpSocket, QTcpServer, and
QUdpSocket.
* /
\endcode
QDoc renders this in \c {qtnetwork.html} like this:
\quotation
\raw HTML
Qt Network Module
\endraw
The Qt Network module offers classes that allow you to
write TCP/IP clients and servers.\l {module
details} {More...}
\raw HTML
|
QAbstractSocket
|
The base functionality common to all socket types
|
|
QFtp
|
Implementation of the FTP protocol
|
| ... |
... |
\endraw
\target module details
\raw HTML
Detailed Description
The Qt Network module offers classes that allow you to
write TCP/IP clients and servers.
The network module provides classes to make network
programming easier and portable. It offers both
high-level classes such as QNetworkAccessManager that
implements application-level protocols, and
lower-level classes such as QTcpSocket, QTcpServer, and
QUdpSocket.
\endraw
...
\endquotation
The \l {noautolist-command} {\\noautolist} command can be used here
to omit the automatically generated list of classes at the end.
See also \l {inmodule-command} {\\inmodule}
\target namespace-command
\section1 \\namespace
The \\namespace command is for documenting the contents of the C++
namespace named as its argument. The documentation outline QDoc
generates for a namespace is similar to the outline it generates
for a C++ class.
\code
/ *!
\namespace Qt
\brief Contains miscellaneous identifiers used throughout the Qt library.
* /
\endcode
QDoc renders this in \c{qt.html} like this:
\quotation
\raw HTML
Qt Namespace Reference
The Qt namespace contains miscellaneous
identifiers used throughout the Qt library.
More...
#include <Qt>
Types
\endraw
\target name
\raw HTML
Detailed Description
Contains miscellaneous identifiers
used throughout the Qt library.
\endraw
...
\endquotation
\target page-command
\section1 \\page
The \\page command is for creating a stand-alone documentation
page. The argument can consist of two parts separated by a
space. The first part is the name of the file where QDoc should
store the page. The second part, if present, is a word that
specifies the page type. Currently, the second part can be one of
the following list of words:
\list
\li faq - A frequently asked question.
\li howto - A user guide on how to use some components of the
software.
\li example - A page that describes a working example.
\li overview - For text pages that provide an overview of some
important subject.
\li tutorial - For text pages that are part of a tutorial.
\li api - This is the type of page used for C++ class references and
QML type references. You should never use this one for the pages
you write, because this one is reserved for qdoc.
\endlist
The page title is set using the \l {title-command} {\\title}
command.
\code
/ *!
\page aboutqt.html
\title About Qt
Qt is a C++ toolkit for cross-platform GUI
application development. Qt provides single-source
portability across Microsoft Windows, macOS, Linux,
and all major commercial Unix variants.
Qt provides application developers with all the
functionality needed to build applications with
state-of-the-art graphical user interfaces. Qt is fully
object-oriented, easily extensible, and allows true
component programming.
...
* /
\endcode
QDoc renders this page in \c {aboutqt.html}.
\target property-command
\section1 \\property
The \\property command is for documenting a Qt property. The
argument is the full property name.
A property is defined using the Q_PROPERTY() macro. The macro
takes as arguments the property's name and its set, reset and get
functions.
\code
Q_PROPERTY(QString state READ state WRITE setState)
\endcode
The set, reset and get functions don't need to be documented,
documenting the property is sufficient. QDoc will generate a list
of the access function that will appear in the property
documentation which in turn will be located in the documentation
of the class that defines the property.
The \\property command comment typically includes a \l
{brief-command} {\\brief} command. For properties the \l
{brief-command} {\\brief} command's argument is a sentence
fragment that will be included in a one line description of the
property. The command follows the same rules for the \l
{brief-property} {description} as the \l {variable-command}
{\\variable} command.
\code
/ *!
\property QPushButton::flat
\brief Whether the border is disabled.
This property's default is false.
* /
\endcode
QDoc includes this in \c {qpushbutton.html} like this:
\quotation
\raw HTML
flat : bool
\endraw
This property holds whether the border is disabled.
This property's default is false.
Access functions:
\list
\li \b { bool isFlat () const}
\li \b { void setFlat ( bool )}
\endlist
\endquotation
\code
/ *!
\property QWidget::width
\brief The width of the widget excluding any window frame.
See the \l {Window Geometry} documentation for an
overview of window geometry.
\sa geometry, height, size
* /
\endcode
QDoc includes this in \c {qwidget.html} like this:
\quotation
\raw HTML
width : const int
\endraw
This property holds the width of the widget excluding
any window frame.
See the \l {Window Geometry} documentation for an
overview of window geometry.
Access functions:
\list
\li \b { int width () const}
\endlist
See also \l{QWidget::geometry} {geometry},
\l{QWidget::height} {height}, and \l{QWidget::size} {size}.
\endquotation
\target qmlattachedproperty-command
\section1 \\qmlattachedproperty
The \\qmlattachedproperty command is for documenting a QML
property that will be attached to some QML type. See
\l{http://doc.qt.io/qt-5/qtqml-syntax-objectattributes.html#attached-properties-and-attached-signal-handlers}
{Attached Properties}. The argument is the rest of the line. The
argument text should be the property type, followed by the QML
element name where the property is being declared, the \c{::}
qualifier, and finally the property name. If we have a QML
attached property named \c isCurrentItem in QML \c ListView,
and the property has type \c {bool}, the \\qmlattachedproperty for
it would look like this:
\code
/ *!
\qmlattachedproperty bool ListView::isCurrentItem
This attached property is \c true if this delegate is the current
item; otherwise false.
It is attached to each instance of the delegate.
This property may be used to adjust the appearance of the current
item, for example:
\snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
* /
\endcode
QDoc includes this attached property on the QML reference page for the
\l{http://doc.qt.io/qt-5/qml-qtquick-listview.html#isCurrentItem-attached-prop}
{ListView} element.
\target qmlattachedsignal-command
\section1 \\qmlattachedsignal
The \\qmlattachedsignal command is for documenting an attachable
\l{Signal and Handler Event System}{signal}. The \\qmlattachedsignal
command is used just like the \l{qmlsignal-command} {\\qmlsignal} command.
The argument is the rest of the line. It should be the name of the
QML type where the signal is declared, the \c{::}
qualifier, and finally the signal name. For example, a QML
attached signal named \c add() in the \c GridView
element is documented like this:
\code
/ *!
\qmlattachedsignal GridView::add()
This attached signal is emitted immediately after an item is added to the view.
* /
\endcode
QDoc includes this documentation on the QML reference page for the
\l GridView element.
\target qmlbasictype-command
\section1 \\qmlbasictype
The \\qmlbasictype command is for documenting a basic type for QML.
The argument is the type name. The type must be included in the
QML basic types group using the \l{ingroup-command}{\\ingroup}
command as shown below. This will cause QDoc to include the
documentation for the type on the
\l{http://doc.qt.io/qt-5/qtqml-typesystem-basictypes.html}
{QML Basic Types} page. The \l{brief-command} {\\brief} command
is also required, because it appears on the
\l{http://doc.qt.io/qt-5/qtqml-typesystem-basictypes.html}
{QML Basic Types} page as well.
\code
/ *!
\qmlbasictype int
\ingroup qmlbasictypes
\brief An integer is a whole number, for example 0, 10, or -20.
An integer is a whole number, e.g. 0, 10, or -20. The possible
\c int values range from around -2000000000 to around
2000000000, although most elements will only accept a reduced
range (which they mention in their documentation).
Example:
\qml
Item { width: 100; height: 200 }
\endqml
\sa {QML Basic Types}
* /
\endcode
QDoc outputs this as \l{http://doc.qt.io/qt-5/qml-int.html}
{qml-int.html}.
\target qmlclass-command
\section1 \\qmlclass
This command is deprecated. Use \l{qmltype-command} {\\qmltype}
instead.
The \\qmlclass command is for documenting a QML type that is
instantiated by a C++ class. The command has two arguments. The
first argument is the name of the QML type. The second argument
is the name of the C++ class that instantiates the QML type.
\code
/ *!
\qmlclass Transform QGraphicsTransform
\ingroup qml-transform-elements
\since 4.7
\brief Provides a way of building advanced transformations on Items.
The Transform element is a base type which cannot be
instantiated directly. The following concrete Transform types
are available:
\list
\li \l Rotation
\li \l Scale
\li \l Translate
\endlist
The Transform elements let you create and control advanced
transformations that can be configured independently using
specialized properties.
You can assign any number of Transform elements to an \l
Item. Each Transform is applied in order, one at a time.
* /
\endcode
This example generates the
\l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
page. The \\qmlclass comment should include the \l
{since-command} {\\since} command, because all QML types are
new. It should also include the \l{brief-command} {\\brief}
command. If a type is a member of a group of QML
types, it should also include one or more \l{ingroup-command}
{\\ingroup} commands.
\target qmlmethod-command
\section1 \\qmlmethod
The \\qmlmethod command is for documenting a QML method. The
argument is the complete method signature, including return
type and parameter names and types.
\code
/ *!
\qmlmethod void TextInput::select(int start, int end)
Causes the text from \a start to \a end to be selected.
If either start or end is out of range, the selection is not changed.
After having called this, selectionStart will become the lesser, and
selectionEnd the greater (regardless of the order passed to this method).
\sa selectionStart, selectionEnd
* /
\endcode
QDoc includes this documentation on the element reference page for the
\l{http://doc.qt.io/qt-5/qml-qtquick-textinput.html#select-method}
{TextInput} element.
\target qmltype-command
\section1 \\qmltype
The \\qmltype command is for documenting a QML type. The command
has one argument, which is the name of the QML type.
If the QML type is instantiated by a C++ class, that class must be
specified using the \l{instantiates-command} {\\instantiates}
context command.
\code
/ *!
\qmltype Transform
\instantiates QGraphicsTransform
\ingroup qml-transform-elements
\since 4.7
\brief The Transform elements provide a way to build
advanced transformations on Items.
The Transform element is a base type which cannot be
instantiated directly. The concrete Transform types are:
\list
\li \l Rotation
\li \l Scale
\li \l Translate
\endlist
The Transform elements let you create and control advanced
transformations that can be configured independently using
specialized properties.
You can assign any number of Transform elements to an \l
Item. Each Transform is applied in order, one at a time.
* /
\endcode
The example generates the \l
{http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
page. The \e{\\qmltype} comment includes \l{instantiates-command}
{\\instantiates} to specify that a Transform is instantiated by
the C++ class QGraphicsTransform. A \\qmltype comment should
always include a \l {since-command} {\\since} command, because all
QML types are new. It should also include a \l{brief-command}
{\\brief} description. If a QML type is a member of a QML type group,
the \\qmltype comment should include one or more \l{ingroup-command}
{\\ingroup} commands.
\target qmlproperty-command
\section1 \\qmlproperty
The \\qmlproperty command is for documenting a QML property. The
argument is the rest of the line. The argument text should be the
property type, followed by the QML type name, the \c{::}
qualifier, and finally the property name. If we have a QML
property named \c x in QML type \c Translate, and the property
has type \c {real}, the \\qmlproperty for it would look like this:
\code
/ *!
\qmlproperty real Translate::x
The translation along the X axis.
* /
\endcode
QDoc includes this QML property on the QML reference page for the
\l {http://doc.qt.io/qt-5/qml-qtquick-translate.html} {Translate}
element.
If the QML property is of enumeration type, or it holds a bit-wise
combination of flags, the \l{value-command}{\\value} command can
be used to document the acceptable values.
\target qmlsignal-command
\section1 \\qmlsignal
The \\qmlsignal command is for documenting a QML signal.
The argument is the rest of the line. The arguments should be: the QML type
where the signal is declared, the \c{::} qualifier, and finally the signal
name. If we have a QML signal named \c clicked(), the documentation for it
would look like this:
\code
/ *!
\qmlsignal QtQuick::MouseArea::clicked(MouseEvent mouse)
This signal is emitted when there is a click. A click is defined as a
press followed by a release, both inside the MouseArea.
* /
\endcode
QDoc includes this documentation on the QML reference page for the
\l{http://doc.qt.io/qt-5/qml-qtquick-mousearea.html#clicked-signal}
{MouseArea} element.
\target qmlmodule-command
\section1 \\qmlmodule
Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML
module is a collection of QML types or any related material. This
command is similar to the \l{group-command}.
A QML class may belong to a module by inserting the
\l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
Every member of a group must be linked to using the module name and two
colons (\c{::}).
\code
\beginqdoc
A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
\endqdoc
\endcode
QDoc will generate a page for the module with a listing of the members
of the module.
\code
\qmlmodule ClickableComponents
This is a list of the Clickable Components set. A Clickable component
responds to a \c clicked() event.
\endcode
The \l{componentset}{UIComponents} example demonstrates proper usage of
QDoc commands to document QML types and QML modules.
\target inqmlmodule-command
\section1 \\inqmlmodule
A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting
the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command, with
the module name (without a version number) as the only argument. Every
member of a group must be linked to using the module name and two colons
(\c{::}).
\code
\qmltype ClickableButton
\inqmlmodule ClickableComponents
A clickable button that responds to the \c click() event.
\endcode
To link to the \c ClickableButton, use the
\c{\l ClickableComponents::ClickableButton} format.
The \l{componentset}{UIComponents} example demonstrates proper usage of
QDoc commands to document QML types and QML modules.
The \l {noautolist-command} {\\noautolist} command can be used here
to omit the automatically generated list of types at the end.
\target instantiates-command
\section1 \\instantiates
The \\instantiates command is used in the \l{qmltype-command} {QML
type} comment of an elemental QML type to specify the name of the
C++ class that instantiates the QML type.
If the QML type is not instantiated by a C++ class, this command
is not used.
\code
/ *!
\qmltype Transform
\instantiates QGraphicsTransform
\ingroup qml-transform-elements
\since 4.7
\brief Provides elements provide a way to build
advanced transformations on Items.
The Transform element is a base type which cannot be
instantiated directly.
* /
\endcode
The example generates the \l
{http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
page. The \e{\\qmltype} comment includes \l{instantiates-command}
{\\instantiates} to specify that a Transform is instantiated by
the C++ class QGraphicsTransform. A \\qmltype comment should
\target typedef-command
\section1 \\typedef
The \\typedef command is for documenting a C++ typedef. The
argument is the name of the typedef. The documentation for
the typedef will be included in the reference documentation
for the class, namespace, or header file in which the typedef
is declared. To relate the \\typedef to a class, namespace, or
header file, the \\typedef comment must contain a
\l {relates-command} {\\relates} command.
\code
/ *!
\typedef QObjectList
\relates QObject
Synonym for QList.
* /
\endcode
QDoc includes this in \c {qobject.html} as:
\quotation
\raw HTML
typedef QObjectList
\endraw
Synonym for QList.
\endquotation
Another, although more rare, example:
\code
/ *!
\typedef QMsgHandler
\relates QtGlobal
This is a typedef for a pointer to a function with the
following signature:
\code
void myMsgHandler(QtMsgType, const char *);
\ endcode
\sa QtMsgType, qInstallMsgHandler()
* /
\endcode
QDoc includes this in \c {qtglobal.html} as:
\quotation
\raw HTML
typedef QtMsgHandler
\endraw
This is a typedef for a pointer to a function with the
following signature:
\raw HTML
void myMsgHandler(QtMsgType, const char *);
\endraw
See also QtMsgType and qInstallMsgHandler().
\endquotation
Other typedefs are located on the reference page for the class
that defines them.
\code
/ *!
\typedef QLinkedList::Iterator
Qt-style synonym for QList::iterator.
* /
\endcode
QDoc includes this one on the reference page for class QLinkedList as:
\quotation
\raw HTML
typedef QLinkedList::Iterator
\endraw
Qt-style synonym for QList::iterator.
\endquotation
\target variable-command
\section1 \\variable
The \\variable command is for documenting a class member variable
or a constant. The argument is the variable or constant name. The
\\variable command comment includes a \l {brief-command} {\\brief}
command. QDoc generates the documentation based on the text from
\\brief command.
The documentation will be located in the in the associated class,
header file, or namespace documentation.
In case of a member variable:
\code
/ *!
\variable QStyleOption::palette
\brief The palette that should be used when painting
the control
* /
\endcode
QDoc includes this in qstyleoption.html as:
\quotation
\raw HTML
QPalette
QStyleOption::palette
\endraw
This variable holds the palette that should be used
when painting the control.
\endquotation
You can also document constants with the \\variable command. For
example, suppose you have the \c Type and \c UserType constants in
the QTreeWidgetItem class:
\code
enum { Type = 0, UserType = 1000 };
\endcode
For these, the \\variable command can be used this way:
\code
/ *!
\variable QTreeWidgetItem::Type
The default type for tree widget items.
\sa UserType, type()
* /
\endcode
\code
/ *!
\variable QTreeWidgetItem::UserType
The minimum value for custom types. Values below
UserType are reserved by Qt.
\sa Type, type()
* /
\endcode
QDoc includes these in qtreewidget.html as:
\quotation
\raw HTML
const int QTreeWidgetItem::Type
\endraw
The default type for tree widget items.
See also \l {QTreeWidgetItem::UserType} {UserType} and \l
{QTreeWidgetItem::type()} {type()}.
\raw HTML
const int QTreeWidgetItem::UserType
\endraw
The minimum value for custom types. Values below
UserType are reserved by Qt.
See also \l {QTreeWidgetItem::Type} {Type} and
\l{QTreeWidgetItem::type()} {type()}.
\endquotation
*/