/*!
\qmlmodule UIComponents 1.0
\title UI Components
- \brief Basic set of QML Components
+ \brief Basic set of UI components
- This is a listing of a list of QML components. These files are available
- for general import and they are based off the \l{Qt Quick Code Samples}.
+ This is a listing of a list of UI components implemented by QML types. These
+ files are available for general import and they are based off the \l{Qt
+ Quick Code Samples}.
This module is part of the \l{componentset}{UIComponents} example.
*/
\example componentset
\title QML Documentation Example
- This example demonstrates one of the ways to document QML components.
+ This example demonstrates one of the ways to document QML types.
- In particular, there are sample components that are documented with QDoc
- commands comments. There are documentation comments for the QML components
- and their public interfaces. The components are grouped into a module, the
+ In particular, there are sample types that are documented with QDoc
+ commands comments. There are documentation comments for the QML types
+ and their public interfaces. The types are grouped into a module, the
\l{UI Components} module.
The \l{componentset/uicomponents.qdoc}{uicomponents.qdoc} file generates
\section1 QML Class
- The components use the \l{qmlclass-command}{\\qmlclass} to document the
- component. In addition, they have the \l{inmodule-command}{\\inmodule}
+ The QML types use the \l{qmlclass-command}{\\qmlclass} to document the
+ type. In addition, they have the \l{inmodule-command}{\\inmodule}
command in order for QDoc to associate them to the \c UIComponents module.
QDoc uses the \l{brief-command}{\\brief} command to place a basic
- description when listing the component.
+ description when listing the types.
\section1 Properties, Signals, Handlers, and Methods
- The components have their properties, signals, handlers, and methods
+ The types have their properties, signals, handlers, and methods
defined in their respective QML files. QDoc associates the properties and
- methods to the components, therefore, you only need to place the
+ methods to the types, therefore, you only need to place the
documentation above the property, method, or signal.
To document the type of a \e {property alias}, you must use the
If you wish to omit certain parts of the documentation, you may use the
\l{omit-command}{\\omit} and \l{omit-command}{\\endomit} command.
- \section1 Components with C++ Implementation
+ \section1 QML Types with C++ Implementation
- This example only demonstrates the documentation for components in QML
+ This example only demonstrates the documentation for types in QML
files, but the regular \l{qml-documentation}{QML commands} may be placed
- inside C++ classes to define the public API of the component.
+ inside C++ classes to define the public API of the QML type.
*/
documentation set. Additionally, the guide presents special considerations
and options to documenting non-C++ API documentation as well as QML
documentation. Finally, the guide will provide a sample project
- documentation and a QML component documentation.
+ documentation and an example of a QML type documentation.
For specific QDoc information, consult the
\l{Table of Contents}{QDoc Manual}.
configuration file.
\code
outputprefixes = QML
- outputprefixes.QML = qml-components-
+ outputprefixes.QML = uicomponents-
\endcode
- The outputprefixes will, for example, prefix QML components HTML filenames.
+ The outputprefixes will, for example, prefix QML type HTML filenames.
\code
files:
- qml-components-button.html
- qml-components-scrollbar.html
+ uicomponents-button.html
+ uicomponents-scrollbar.html
\endcode
*/
\list
\li \l{enum-command}{\\enum} - for enumeration documentation
\li \l{class-command}{\\class} - for C++ class documentation
- \li \l{qmlclass-command}{\\qmlclass} - for QML component documentation
+ \li \l{qmlclass-command}{\\qmlclass} - for QML type documentation
\li \l{page-command}{\\page} - for creating a page.
\endlist
\li Article
\li FAQ (Frequently Asked Questions)
\li C++ API Documentation
- \li QML Component Documentation
+ \li QML Type Documentation
\li Code Example
\endlist
not properly process QDoc comments in header files.
\keyword qml-documentation
- \section2 Documenting QML Components
+ \section2 Documenting QML Types
In the world of \l{Qt Quick}{QML}, there are additional entities we need to
document such as QML signals, attached properties, and QML methods.
\li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
\li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
\li \l{qmlbasictype-command}{\\qmlbasictype}
- \li \l{qmlclass-command}{\\qmlclass} - creates a QML component documentation
+ \li \l{qmlclass-command}{\\qmlclass} - creates a QML type documentation
\li \l{qmlmethod-command}{\\qmlmethod}
\li \l{qmlproperty-command}{\\qmlproperty}
\li \l{qmlsignal-command}{\\qmlsignal}
\section3 QML Modules
- A component belongs to a component \e set or a \e module. The module
- may include all the related components for a platform or contain a certain
+ A QML type belongs to a \e module. The module
+ may include all the related types for a platform or contain a certain
version of \l{Qt Quick}. For example, the Qt Quick 2 \l{QML Elements} belong
to the QtQuick2 module while there is also a QtQuick1 module for the older
- elements introduced in Qt 4.
+ types introduced in Qt 4.
- Modules affect the way Qdoc link and relate the components. The
+ Modules affect the way Qdoc link and relate the types. The
\l{qmlclass-command}{\\qmlclass} topic command must have an
\l{inqmlmodule-command}{\\inqmlmodule} context command to relate the
- component to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
+ type to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
command must exist in a separate \c .qdoc file to create the overview page
- for the module. The overview page will list the related components.
+ for the module. The overview page will list the related types.
- The links to the components, must therefore, also contain the module name.
- For example, if a component called \c TabWidget is in the \c UIComponents
+ The links to the QML types, must therefore, also contain the module name.
+ For example, if a type called \c TabWidget is in the \c UIComponents
module, it must be linked as \c {UIComponents::TabWidget}.
The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML components and QML modules.
+ QDoc commands to document QML types and QML modules.
\section3 Read-only and Internal QML Properties
\code
readonly property int sampleReadOnlyProperty: 0
\endcode
- For example, the example \l{TabWidget} component has a fictitious read-only
+ For example, the example \l{TabWidget} type has a fictitious read-only
property \c sampleReadOnlyProperty. Its declaration has the \c readonly
identifier and it has an initial value.
\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 element references, etc. You should never use this one for
+ and QML type references, etc. You should never use this one for
the pages you write, because this one is reserved for qdoc.
\endlist
\section1 \\qmlattachedproperty
The \\qmlattachedproperty command is for documenting a QML
- property that will be attached to some QML element type. See
+ property that will be attached to some QML type. See
\l{http://doc.qt.nokia.com/4.7/qdeclarativeintroduction.html#attached-properties}
{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 element \c ListView,
+ attached property named \c isCurrentItem in QML \c ListView,
and the property has type \c {bool}, the \\qmlattachedproperty for
it would look like this:
the \l{qmlsignal-command} {\\qmlsignal} command.
The argument is the rest of the line. It should be the name of the
- QML element where the signal handler is declared, the \c{::}
+ QML type where the signal handler is declared, the \c{::}
qualifier, and finally the signal handler name. If we have a QML
attached signal handler named \c onAdd() in the \c GridView
element, the \\qmlattachedsignal for it would look like this:
\target qmlclass-command
\section1 \\qmlclass
- The \\qmlclass command is for documenting a QML element that is
+ 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 element. The second argument
- is the name of the C++ class that instantiates the QML element.
+ 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
/ *!
\endcode
This example generates the
- \l {http://doc.qt.nokia.com/4.7/qml-transform.html} {QML Transform
- Element} page. The \\qmlclass comment should include the \l
- {since-command} {\\since} command, because all QML elements are
+ \l {http://doc.qt.nokia.com/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. And since every QML element is a member of a group of QML
- elements, it should also include one or more \l{ingroup-command}
+ command. And 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
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 element name, the \c{::}
+ 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 element \c Translate, and the property
+ 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
The \\qmlsignal command is for documenting a
\l{http://doc.qt.nokia.com/4.7/qdeclarativeintroduction.html#signal-handlers}
{signal handler}.
- The argument is the rest of the line. It should be the QML element where the
+ The argument is the rest of the line. It should be the QML type where the
signal handler is declared, the \c{::} qualifier, and finally the signal
handler name. If we have a QML signal handler named \c onAdd() in QML
element \c MouseArea, the \\qmlsignal for it would look like this:
\section1 \\qmlmodule
Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML
- module is a collection of QML components or any related material. This
+ 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
\endcode
The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML components and QML modules.
+ QDoc commands to document QML types and QML modules.
\target inqmlmodule-command
\section1 \\inqmlmodule
\c{\l ClickableComponents::ClickableButton} format.
The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML components and QML modules.
+ QDoc commands to document QML types and QML modules.
\target typedef-command
\section1 \\typedef
See how QDoc renders this property on the reference page for the
\l {http://doc.qt.nokia.com/4.7/qml-state.html#changes-prop} {State}
- element.
+ type.
\target obsolete-command
\section1 \\obsolete
is an overload of another function, or this function is a
reimplementation of another function, or this typedef is \e
related to some class or header file. There is also a command
- for documenting that a QML element inherits some other QML
- element.
+ 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 element
- inherits some other QML element. It must be included in the
+ 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{qmlclass-command}{\\qmlclass} comment.
- The argument is the name of the inherited QML element.
+ The argument is the name of the inherited QML type.
\code
/ *!
\code
outputprefixes = QML
- outputprefixes.QML = qt-components-
+ outputprefixes.QML = uicomponents-
\endcode
- By default, files containing the API documentation for QML elements
- or components are prefixed with "qml-". In the above example, the
- prefix "qt-components-" is used instead.
+ By default, files containing the API documentation for QML types
+ are prefixed with "qml-". In the above example, the
+ prefix \c "uicomponents" is used instead.
\target qhp-variable
\section1 qhp
projects / profile / ivi / qtbase.git / commitdiff