whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

QDoc: updating manual to use "type". 

-updated both QDoc manual and QDoc guide
-"QML element" and "QML component" should be "QML type"

Change-Id: Ib2a0e8baa9087a04d35c05bbbd35852da10faf42
Reviewed-by: Martin Smith <martin.smith@nokia.com>
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
bb10
Jerome Pasion 2012-03-21 12:22:19 +01:00 committed by Qt by Nokia
parent 3ba8d3b4b0
commit df6a08951a
4 changed files with 63 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc
View File

@ -28,10 +28,11 @@
/*!
\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.
*/

24
src/tools/qdoc/doc/examples/examples.qdoc
View File

@ -29,11 +29,11 @@
\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
@ -43,18 +43,18 @@
\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
@ -75,10 +75,10 @@
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.
*/

38
src/tools/qdoc/doc/qdoc-guide.qdoc
View File

@ -48,7 +48,7 @@
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}.
@ -246,13 +246,13 @@
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
*/
@ -295,7 +295,7 @@
\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
@ -411,7 +411,7 @@
\li Article
\li FAQ (Frequently Asked Questions)
\li C++ API Documentation
\li QML Component Documentation
\li QML Type Documentation
\li Code Example
\endlist
@ -440,7 +440,7 @@
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.
@ -453,7 +453,7 @@
\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}
@ -511,25 +511,25 @@
\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
@ -539,7 +539,7 @@
\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.

56
src/tools/qdoc/doc/qdoc-manual.qdoc
View File

@ -5202,7 +5202,7 @@
\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
@ -5351,13 +5351,13 @@
\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:
@ -5389,7 +5389,7 @@
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:
@ -5447,10 +5447,10 @@
\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
/ *!
@ -5481,12 +5481,12 @@
\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
@ -5521,9 +5521,9 @@
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
@ -5544,7 +5544,7 @@
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:
@ -5571,7 +5571,7 @@
\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
@ -5594,7 +5594,7 @@
\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
@ -5615,7 +5615,7 @@
\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
@ -6154,7 +6154,7 @@
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
@ -6538,18 +6538,18 @@
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
/ *!
@ -7957,12 +7957,12 @@
\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