qdoc: Changed \qmlclass to \qmltype, added \instantiates

The \qmlclass qdoc command is now deprecated. Use \qmltype instead.
\qmlclass had two arguments, the QML type name and, if the QML type
was elemental, the name of the C++ class that the QML element
instantiates. The \qmltype command has only one argument, the QML type
name.

If the QML type is elemental, then the \qmltype command should be
followed by a \instantiates context command in the same qdoc
comment. e.g.:

\qmltype Item
\instantiates QDeclarativeItem

When the developer does not include the \instantiates command for an
elemental QML type, qdoc will no longer be able to detect that the C++
class name is missing, and qdoc will no longer be able to detect when
the name specified for a \qmlproperty of the elemental QML type has
the wrong name.

Task nr: QTBUG-26648

Change-Id: Ia60872a35113a6f615bfc751ce1e9db6279dfb8e
Reviewed-by: Casper van Donderen <[email protected]>

1 files changed, 39 insertions, 4 deletions

diff --git a/src/tools/qdoc/cppcodeparser.cpp b/src/tools/qdoc/cppcodeparser.cpp
index 02b81eeb1bd..c95e03f5f7b 100644
--- a/src/tools/qdoc/cppcodeparser.cpp
+++ b/src/tools/qdoc/cppcodeparser.cpp
@@ -474,6 +474,7 @@ QSet<QString> CppCodeParser::topicCommands()
                            << COMMAND_TYPEDEF
                            << COMMAND_VARIABLE
                            << COMMAND_QMLCLASS
+                           << COMMAND_QMLTYPE
                            << COMMAND_QMLPROPERTY
                            << COMMAND_QMLATTACHEDPROPERTY
                            << COMMAND_QMLSIGNAL
@@ -725,11 +726,29 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
         fn->setLocation(doc.startLocation());
         return fn;
     }
-    else if (command == COMMAND_QMLCLASS) {
+    else if ((command == COMMAND_QMLCLASS) || (command == COMMAND_QMLTYPE)) {
+        if (command == COMMAND_QMLCLASS)
+            doc.startLocation().warning(tr("\\qmlclass is deprecated; use \\qmltype instead"));
         ClassNode* classNode = 0;
         QStringList names = arg.first.split(QLatin1Char(' '));
-        if (names.size() > 1)
-            classNode = tree_->findClassNode(names[1].split("::"));
+        if (names.size() > 1) {
+            if (names[1] != "0")
+                doc.startLocation().warning(tr("\\qmltype no longer has a 2nd argument; "
+                                               "use '\\instantiates <class>' in \\qmltype "
+                                               "comments instead"));
+            else
+                doc.startLocation().warning(tr("The 0 arg is no longer used for indicating "
+                                               "that the QML type does not instantiate a "
+                                               "C++ class"));
+            /*
+              If the second argument of the \\qmlclass command
+              is 0 we should ignore the C++ class. The second
+              argument should only be 0 when you are documenting
+              QML in a .qdoc file.
+             */
+            if (names[1] != "0")
+                classNode = tree_->findClassNode(names[1].split("::"));
+        }
 
         /*
           Search for a node with the same name. If there is one,
@@ -743,8 +762,11 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
           node and return that one.
          */
         NameCollisionNode* ncn = tree_->checkForCollision(names[0]);
-        QmlClassNode* qcn = new QmlClassNode(tree_->root(), names[0], classNode);
+        QmlClassNode* qcn = new QmlClassNode(tree_->root(), names[0]);
+        qcn->setClassNode(classNode);
         qcn->setLocation(doc.startLocation());
+#if 0
+        // to be removed if \qmltype and \instantiates work ok
         if (isParsingCpp() || isParsingQdoc()) {
             qcn->requireCppClass();
             if (names.size() < 2) {
@@ -758,6 +780,7 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
                 doc.startLocation().warning(tr(msg.toLatin1().data()));
             }
         }
+#endif
         if (ncn)
             ncn->addCollision(qcn);
         return qcn;
@@ -984,6 +1007,7 @@ QSet<QString> CppCodeParser::otherMetaCommands()
                                 << COMMAND_INDEXPAGE
                                 << COMMAND_STARTPAGE
                                 << COMMAND_QMLINHERITS
+                                << COMMAND_QMLINSTANTIATES
                                 << COMMAND_QMLDEFAULT
                                 << COMMAND_QMLREADONLY
                                 << COMMAND_QMLABSTRACT;
@@ -1110,6 +1134,17 @@ void CppCodeParser::processOtherMetaCommand(const Doc& doc,
             }
         }
     }
+    else if (command == COMMAND_QMLINSTANTIATES) {
+        if ((node->type() == Node::Fake) && (node->subType() == Node::QmlClass)) {
+            ClassNode* classNode = tree_->findClassNode(arg.split("::"));
+            if (classNode)
+                node->setClassNode(classNode);
+            else
+                doc.location().warning(tr("C++ class %1 not found: \\instantiates %1").arg(arg));
+        }
+        else
+            doc.location().warning(tr("\\instantiates is only allowed in \\qmltype"));
+    }
     else if (command == COMMAND_QMLDEFAULT) {
         if (node->type() == Node::QmlProperty) {
             QmlPropertyNode* qpn = static_cast<QmlPropertyNode*>(node);