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 <jerome.pasion@nokia.com>

6 files changed, 143 insertions, 26 deletions

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}