From df6a08951af9005ef86d3eb43ef2816a74837a9f Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 21 Mar 2012 12:22:19 +0100 Subject: 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 Reviewed-by: Casper van Donderen --- .../doc/examples/componentset/uicomponents.qdoc | 7 +-- src/tools/qdoc/doc/examples/examples.qdoc | 24 +++++----- src/tools/qdoc/doc/qdoc-guide.qdoc | 38 +++++++-------- src/tools/qdoc/doc/qdoc-manual.qdoc | 56 +++++++++++----------- 4 files changed, 63 insertions(+), 62 deletions(-) (limited to 'src/tools/qdoc/doc') diff --git a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc index 10c23c7c0f..ad61daa3ca 100644 --- a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc +++ b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc @@ -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. */ diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc index 800589b9ac..236e7ae74a 100644 --- a/src/tools/qdoc/doc/examples/examples.qdoc +++ b/src/tools/qdoc/doc/examples/examples.qdoc @@ -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. */ diff --git a/src/tools/qdoc/doc/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide.qdoc index 33cc5c67fd..a875c48770 100644 --- a/src/tools/qdoc/doc/qdoc-guide.qdoc +++ b/src/tools/qdoc/doc/qdoc-guide.qdoc @@ -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. diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc index e6bdf5af27..342cabc432 100644 --- a/src/tools/qdoc/doc/qdoc-manual.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual.qdoc @@ -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 -- cgit v1.2.3