Doc: Fixed handling of versioned properties and added documentation.

Task-number: QTBUG-13451

5 files changed, 84 insertions, 85 deletions

diff --git a/doc/src/objectmodel/properties.qdoc b/doc/src/objectmodel/properties.qdoc
index 77421c5..92c182e 100644
--- a/doc/src/objectmodel/properties.qdoc
+++ b/doc/src/objectmodel/properties.qdoc
@@ -83,6 +83,10 @@
     existing signal in that class that is emitted whenever the value
     of the property changes.
 
+    \o A \c REVISION number is optional. If included, it defines the
+    the property and its notifier signal to be used in a particular
+    revision of the API that is exposed to QML.
+
     \o The \c DESIGNABLE attribute indicates whether the property
     should be visible in the property editor of GUI design tool (e.g.,
     \l {Qt Designer}). Most properties are \c DESIGNABLE (default
diff --git a/doc/src/snippets/code/doc_src_properties.cpp b/doc/src/snippets/code/doc_src_properties.cpp
index 1238bc5..b5a103d 100644
--- a/doc/src/snippets/code/doc_src_properties.cpp
+++ b/doc/src/snippets/code/doc_src_properties.cpp
@@ -44,6 +44,7 @@ Q_PROPERTY(type name
            [WRITE setFunction]
            [RESET resetFunction]
            [NOTIFY notifySignal]
+           [REVISION int]
            [DESIGNABLE bool]
            [SCRIPTABLE bool]
            [STORED bool]
diff --git a/tools/qdoc3/cppcodeparser.cpp b/tools/qdoc3/cppcodeparser.cpp
index 3979176..595756a 100644
--- a/tools/qdoc3/cppcodeparser.cpp
+++ b/tools/qdoc3/cppcodeparser.cpp
@@ -863,10 +863,12 @@ Node *CppCodeParser::processTopicCommandGroup(const Doc& doc,
         }
         if (qmlPropGroup) {
             const ClassNode *correspondingClass = static_cast<const QmlClassNode*>(qmlPropGroup->parent())->classNode();
-            PropertyNode *correspondingProperty = 0;
-            if (correspondingClass)
-                correspondingProperty = static_cast<PropertyNode*>((Node*)correspondingClass->findNode(property, Node::Property));
             QmlPropertyNode *qmlPropNode = new QmlPropertyNode(qmlPropGroup,property,type,attached);
+
+            const PropertyNode *correspondingProperty = 0;
+            if (correspondingClass) {
+                correspondingProperty = qmlPropNode->correspondingProperty(tre);
+            }
             if (correspondingProperty) {
                 bool writableList = type.startsWith("list") && correspondingProperty->dataType().endsWith('*');
                 qmlPropNode->setWritable(writableList || correspondingProperty->isWritable());
@@ -1829,7 +1831,7 @@ bool CppCodeParser::matchProperty(InnerNode *parent)
         QString key = previousLexeme();
         QString value;
 
-        if (match(Tok_Ident)) {
+        if (match(Tok_Ident) || match(Tok_Number)) {
             value = previousLexeme();
         }
         else if (match(Tok_LeftParen)) {
@@ -1872,8 +1874,15 @@ bool CppCodeParser::matchProperty(InnerNode *parent)
             tre->addPropertyFunction(property, value, PropertyNode::Resetter);
         else if (key == "NOTIFY") {
             tre->addPropertyFunction(property, value, PropertyNode::Notifier);
-        }
-        else if (key == "SCRIPTABLE") {
+        } else if (key == "REVISION") {
+            int revision;
+            bool ok;
+            revision = value.toInt(&ok);
+            if (ok)
+                property->setRevision(revision);
+            else
+                parent->doc().location().warning(tr("Invalid revision number: %1").arg(value));
+        } else if (key == "SCRIPTABLE") {
             QString v = value.toLower();
             if (v == "true")
                 property->setScriptable(true);
@@ -1884,7 +1893,7 @@ bool CppCodeParser::matchProperty(InnerNode *parent)
                 property->setRuntimeScrFunc(value);
             }
         }
-        else if (key == "COSTANT") 
+        else if (key == "CONSTANT") 
             property->setConstant();
         else if (key == "FINAL") 
             property->setFinal();
diff --git a/tools/qdoc3/node.cpp b/tools/qdoc3/node.cpp
index 7195322..ee050f5 100644
--- a/tools/qdoc3/node.cpp
+++ b/tools/qdoc3/node.cpp
@@ -947,10 +947,35 @@ void ClassNode::fixBaseClasses()
   Search the child list to find the property node with the
   specified \a name.
  */
-const PropertyNode* ClassNode::findPropertyNode(const QString& name) const
+const PropertyNode *ClassNode::findPropertyNode(const QString &name) const
 {
-    const Node* n = findNode(name,Node::Property);
-    return (n ? static_cast<const PropertyNode*>(n) : 0);
+    const Node *n = findNode(name, Node::Property);
+
+    if (n)
+        return static_cast<const PropertyNode*>(n);
+
+    const PropertyNode *pn = 0;
+
+    const QList<RelatedClass> &bases = baseClasses();
+    if (!bases.isEmpty()) {
+        for (int i = 0; i < bases.size(); ++i) {
+            const ClassNode *cn = bases[i].node;
+            pn = cn->findPropertyNode(name);
+            if (pn)
+                break;
+        }
+    }
+    const QList<RelatedClass>& ignoredBases = ignoredBaseClasses();
+    if (!ignoredBases.isEmpty()) {
+        for (int i = 0; i < ignoredBases.size(); ++i) {
+            const ClassNode *cn = ignoredBases[i].node;
+            pn = cn->findPropertyNode(name);
+            if (pn)
+                break;
+        }
+    }
+
+    return pn;
 }
 
 /*!
@@ -1406,6 +1431,7 @@ PropertyNode::PropertyNode(InnerNode *parent, const QString& name)
       usr(Trool_Default),
       cst(false),
       fnl(false),
+      rev(-1),
       overrides(0)
 {
     // nothing.
@@ -1657,7 +1683,7 @@ bool QmlPropertyNode::fromTrool(Trool troolean, bool defaultValue)
     }
 }
 
-static QString valueType(const QString& n)
+static QString valueType(const QString &n)
 {
     if (n == "QPoint")
         return "QDeclarativePointValueType";
@@ -1700,6 +1726,19 @@ bool QmlPropertyNode::isWritable(const Tree* tree) const
     if (wri != Trool_Default)
         return fromTrool(wri, false);
 
+    const PropertyNode *pn = correspondingProperty(tree);
+    if (pn)
+        return pn->isWritable();
+    else {
+        location().warning(tr("Can't determine read-only status of QML property %1; writable assumed.").arg(name()));
+        return true;
+    }
+}
+
+const PropertyNode *QmlPropertyNode::correspondingProperty(const Tree *tree) const
+{
+    const PropertyNode *pn;
+
     Node* n = parent();
     while (n && n->subType() != Node::QmlClass)
         n = n->parent();
@@ -1708,93 +1747,35 @@ bool QmlPropertyNode::isWritable(const Tree* tree) const
         const ClassNode* cn = qcn->classNode();
         if (cn) {
             QStringList dotSplit = name().split(QChar('.'));
-            const PropertyNode* pn = cn->findPropertyNode(dotSplit[0]);
+            pn = cn->findPropertyNode(dotSplit[0]);
             if (pn) {
                 if (dotSplit.size() > 1) {
+                    // Find the C++ property corresponding to the QML property in
+                    // the property group, <group>.<property>.
+
                     QStringList path(extractClassName(pn->qualifiedDataType()));
                     const Node* nn = tree->findNode(path,Class);
                     if (nn) {
                         const ClassNode* cn = static_cast<const ClassNode*>(nn);
-                        pn = cn->findPropertyNode(dotSplit[1]);
-                        if (pn) {
-                            return pn->isWritable();
-                        }
-                        else {
-                            const QList<RelatedClass>& bases = cn->baseClasses();
-                            if (!bases.isEmpty()) {
-                                for (int i=0; i<bases.size(); ++i) {
-                                    const ClassNode* cn = bases[i].node;
-                                    pn = cn->findPropertyNode(dotSplit[1]);
-                                    if (pn) {
-                                        return pn->isWritable();
-                                    }
-                                }
-                            }
-                            const QList<RelatedClass>& ignoredBases = cn->ignoredBaseClasses();
-                            if (!ignoredBases.isEmpty()) {
-                                for (int i=0; i<ignoredBases.size(); ++i) {
-                                    const ClassNode* cn = ignoredBases[i].node;
-                                    pn = cn->findPropertyNode(dotSplit[1]);
-                                    if (pn) {
-                                        return pn->isWritable();
-                                    }
-                                }
-                            }
-                            QString vt = valueType(cn->name());
-                            if (!vt.isEmpty()) {
-                                QStringList path(vt);
-                                const Node* vtn = tree->findNode(path,Class);
-                                if (vtn) {
-                                    const ClassNode* cn = static_cast<const ClassNode*>(vtn);
-                                    pn = cn->findPropertyNode(dotSplit[1]);
-                                    if (pn) {
-                                        return pn->isWritable();
-                                    }
-                                }
-                            }
-                        }
+                        const PropertyNode *pn2 = cn->findPropertyNode(dotSplit[1]);
+                        if (pn2)
+                            return pn2; // Return the property for the QML property.
+                        else
+                            return pn;  // Return the property for the QML group.
                     }
                 }
-                else {
-                    return pn->isWritable();
-                }
+                else
+                    return pn;
             }
             else {
-                const QList<RelatedClass>& bases = cn->baseClasses();
-                if (!bases.isEmpty()) {
-                    for (int i=0; i<bases.size(); ++i) {
-                        const ClassNode* cn = bases[i].node;
-                        pn = cn->findPropertyNode(dotSplit[0]);
-                        if (pn) {
-                            return pn->isWritable();
-                        }
-                    }
-                }
-                const QList<RelatedClass>& ignoredBases = cn->ignoredBaseClasses();
-                if (!ignoredBases.isEmpty()) {
-                    for (int i=0; i<ignoredBases.size(); ++i) {
-                        const ClassNode* cn = ignoredBases[i].node;
-                        pn = cn->findPropertyNode(dotSplit[0]);
-                        if (pn) {
-                            return pn->isWritable();
-                        }
-                    }
-                }
-                if (isAttached()) {
-                    QString classNameAttached = cn->name() + "Attached";
-                    QStringList path(classNameAttached);
-                    const Node* nn = tree->findNode(path,Class);
-                    const ClassNode* acn = static_cast<const ClassNode*>(nn);
-                    pn = acn->findPropertyNode(dotSplit[0]);
-                    if (pn) {
-                        return pn->isWritable();
-                    }
-                }
+                pn = cn->findPropertyNode(dotSplit[0]);
+                if (pn)
+                    return pn;
             }
         }
     }
-    location().warning(tr("Can't determine read-only status of QML property %1; writable assumed.").arg(name()));
-    return true;
+
+    return 0;
 }
 
 #endif
diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h
index aa7c78a..d1123dc 100644
--- a/tools/qdoc3/node.h
+++ b/tools/qdoc3/node.h
@@ -466,6 +466,8 @@ class QmlPropertyNode : public LeafNode
     bool isAttached() const { return att; }
     virtual bool isQmlNode() const { return true; }
 
+    const PropertyNode *correspondingProperty(const Tree *tree) const;
+
     const QString& element() const { return static_cast<QmlPropGroupNode*>(parent())->element(); }
 
  private:
@@ -689,6 +691,7 @@ class PropertyNode : public LeafNode
     void setRuntimeScrFunc(const QString& scrf) { runtimeScrFunc = scrf; }
     void setConstant() { cst = true; }
     void setFinal() { fnl = true; }
+    void setRevision(int revision) { rev = revision; }
 
     const QString &dataType() const { return dt; }
     QString qualifiedDataType() const;
@@ -732,6 +735,7 @@ class PropertyNode : public LeafNode
     Trool usr;
     bool cst;
     bool fnl;
+    int rev;
     const PropertyNode* overrides;
 };