From be46199c624d307b891ebb141772f00aecd71ad2 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Fri, 27 Jul 2012 12:22:05 +0200 Subject: qdoc: Updated qdoc manual and qdoc guide These documents now include the \qmltype and \instantiates commands, and the \qmlclass command is deprecated. Task nr: QTBUG-26648 Change-Id: I62da273be51609e651e33b9088e1667e4c6c1e76 Reviewed-by: Jerome Pasion --- .../qdoc/doc/examples/componentset/ProgressBar.qml | 2 +- .../qdoc/doc/examples/componentset/Switch.qml | 2 +- .../qdoc/doc/examples/componentset/TabWidget.qml | 2 +- src/tools/qdoc/doc/examples/examples.qdoc | 2 +- src/tools/qdoc/doc/qdoc-guide.qdoc | 34 +++--- src/tools/qdoc/doc/qdoc-manual.qdoc | 127 +++++++++++++++++++-- 6 files changed, 143 insertions(+), 26 deletions(-) (limited to 'src/tools/qdoc/doc') diff --git a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml b/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml index 5255e864ac..e3867e9783 100644 --- a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml +++ b/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml @@ -41,7 +41,7 @@ import QtQuick 1.0 /*! - \qmlclass ProgressBar + \qmltype ProgressBar \inqmlmodule UIComponents 1.0 \brief A component that shows the progress of an event diff --git a/src/tools/qdoc/doc/examples/componentset/Switch.qml b/src/tools/qdoc/doc/examples/componentset/Switch.qml index 31153d6252..48d69e434f 100644 --- a/src/tools/qdoc/doc/examples/componentset/Switch.qml +++ b/src/tools/qdoc/doc/examples/componentset/Switch.qml @@ -41,7 +41,7 @@ import QtQuick 1.0 /*! - \qmlclass ToggleSwitch + \qmltype ToggleSwitch \inqmlmodule UIComponents 1.0 \brief A component that can be turned on or off diff --git a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml b/src/tools/qdoc/doc/examples/componentset/TabWidget.qml index eb64979fb2..3b737a42d7 100644 --- a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml +++ b/src/tools/qdoc/doc/examples/componentset/TabWidget.qml @@ -41,7 +41,7 @@ import QtQuick 1.0 /*! - \qmlclass TabWidget + \qmltype TabWidget \inqmlmodule UIComponents 1.0 \brief A widget that places its children as tabs diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc index 236e7ae74a..80b3231226 100644 --- a/src/tools/qdoc/doc/examples/examples.qdoc +++ b/src/tools/qdoc/doc/examples/examples.qdoc @@ -43,7 +43,7 @@ \section1 QML Class - The QML types use the \l{qmlclass-command}{\\qmlclass} to document the + The QML types use the \l{qmltype-command}{\\qmltype} 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. diff --git a/src/tools/qdoc/doc/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide.qdoc index e57c3857c5..64dc78cd2d 100644 --- a/src/tools/qdoc/doc/qdoc-guide.qdoc +++ b/src/tools/qdoc/doc/qdoc-guide.qdoc @@ -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 type documentation + \li \l{qmltype-command}{\\qmltype} - for QML type documentation \li \l{page-command}{\\page} - for creating a page. \endlist @@ -453,13 +453,14 @@ \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} \li \l{qmlbasictype-command}{\\qmlbasictype} - \li \l{qmlclass-command}{\\qmlclass} - creates a QML type documentation + \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation \li \l{qmlmethod-command}{\\qmlmethod} \li \l{qmlproperty-command}{\\qmlproperty} \li \l{qmlsignal-command}{\\qmlsignal} \li \l{inherits-command}{\\inherits} \li \l{qmlmodule-command}{\\qmlmodule} \li \l{inqmlmodule-command}{\\inqmlmodule} + \li \l{instantiates-command}{\\instantiates} \endlist @@ -467,18 +468,20 @@ the \l{qdoc-input-output-dir}{fileextension} variable. To document a QML type, start by creating a QDoc comment that uses the - \l{qmlclass-command} {\\qmlclass} command as its topic command. + \l{qmltype-command} {\\qmltype} command as its topic command. \section3 QML Parser If your QML type is defined in a \e qml file, document it there. If your QML type is represented by a C++ class, document it in the - \e cpp file for that C++ class. Don't document a QML type in a - \e{cpp} file if the QML type is defined in a \e{qml} file. + \e cpp file for that C++ class and include an + \l{instantiates-command}{\\instantiates} command to specify the + name of the C++ class. Don't document a QML type in a \e{cpp} file + if the QML type is defined in a \e{qml} file. When documenting a QML type in a \e{qml} file, place each QDoc comment directly above the entity to which the comment applies. - For example, place the QDoc comment containing the \e{\\qmlclass} + For example, place the QDoc comment containing the \e{\\qmltype} command (the topic comment) directly above the outer QML type in the \e{qml} file. Place the comment for documenting a QML property directly above the property declaration, and so on for QML signal @@ -504,8 +507,8 @@ does not use the QML parser to parse these files (the C++ parser is used), so these QML QDoc comments can appear anywhere in the \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must - use the QML topic commands. i.e., the \l{qmlclass-command} - {\\qmlclass} command \e must appear in the QDoc comment for the + use the QML topic commands. i.e., the \l{qmltype-command} + {\\qmltype} command \e must appear in the QDoc comment for the QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e must appear in each QML property QDoc comment. @@ -517,14 +520,15 @@ to the QtQuick2 module while there is also a QtQuick1 module for the older types introduced in Qt 4. - 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 - 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 types. + QML modules allow grouping QML types. The \l{qmltype-command} + {\\qmltype} topic command must have an \l{inqmlmodule-command} + {\\inqmlmodule} context command to relate the type to a QML + 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 + QML types of the QML module. - The links to the QML types, must therefore, also contain the module name. + 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}. diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc index 2b4d16029e..126e00ab46 100644 --- a/src/tools/qdoc/doc/qdoc-manual.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual.qdoc @@ -3525,9 +3525,10 @@ * / \endcode - This generates a list of all the classes in the \e{draganddrop} group. - A class in the \e{draganddrop} group will have the \\ingroup command - in its \\class or \\qmlclass comment. + This generates a list of all the C++ classes and/or QML types in + the \e{draganddrop} group. A C++ class or QML type in the + \e{draganddrop} group will have \e{\\ingroup draganddrop} in its + \e{\\class} or \e{\\qmltype} comment. \target generatelist-command @@ -5428,6 +5429,9 @@ \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 @@ -5497,6 +5501,82 @@ \l{http://doc.qt.nokia.com/4.7/qml-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://doc.qt.nokia.com/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. And if a QML type is a member of a group of + QML types, the \\qmltype comment should 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 calling this, selectionStart will become the lesser and + selectionEnd will become the greater (regardless of the order + passed to this method). + + \sa selectionStart, selectionEnd + * / + \endcode + + QDoc includes this documentation on the element refence page for the + \l{http://doc.qt.nokia.com/4.7/qml-textinput.html#select-method} + {TextInput} element. + \target qmlproperty-command \section1 \\qmlproperty @@ -5579,7 +5659,7 @@ colons (\c{::}). \code - \qmlclass ClickableButton + \qmltype ClickableButton \inqmlmodule ClickableComponents A clickable button that responds to the \c click() event. @@ -5591,6 +5671,36 @@ The \l{componentset}{UIComponents} example demonstrates proper usage of QDoc commands to document QML types and QML modules. + \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 The Transform 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://doc.qt.nokia.com/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 @@ -6522,12 +6632,13 @@ 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. + inheriting element's \l{qmltype-command}{\\qmltype} comment. The argument is the name of the inherited QML type. \code / *! - \qmlclass PauseAnimation QDeclarativePauseAnimation + \qmltype PauseAnimation + \instantiates QDeclarativePauseAnimation \ingroup qml-animation-transition \since 4.7 \inherits Animation @@ -8686,12 +8797,14 @@ \li \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \li \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \li \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} - \li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} + \li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)} + \li \l {13-qdoc-commands-topics.html#qmltype-command} {\\qmltype} \span {class="newStuff"} {(new 27/7/2012)} \li \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \li \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \li \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \li \l {13-qdoc-commands-topics.html#qmlmodule-command} {\\qmlmodule} \li \l {13-qdoc-commands-topics.html#inqmlmodule-command} {\\inqmlmodule} + \li \l {13-qdoc-commands-topics.html#instantiates-command} {\\instantiates} \span {class="newStuff"} {(new 27/7/2012)} \li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} -- cgit v1.2.3