Improve documentation for var properties

Previously, the initialization value assignment semantics of var
properties wasn't explicitly documented.  Since curly braces on the
RHS of an initialization assignment denotes a binding (and curly
braces have a different meaning in JavaScript) confusion could result.

This commit clearly explains how to initialize a var property with an
empty object value.

Task-number: QTBUG-23734
Task-number: QTBUG-23388
Change-Id: Ifa94846b170919a0c893f7dda1421c9fb24bd0db
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc
index 55438c3..e5f0c21 100644 (file)
--- a/src/qml/doc/src/typesystem/basictypes.qdoc
+++ b/src/qml/doc/src/typesystem/basictypes.qdoc
@@ -699,6 +699,8 @@ property is only invoked when the property is reassigned to a different object v
     }
     \endqml
 
+    \section1 Change Notification Semantics
+
     It is important to note that changes in regular properties of JavaScript
     objects assigned to a var property will \b{not} trigger updates of bindings
     that access them.  The example below will display "The car has 4 wheels" as
@@ -724,6 +726,48 @@ property is only invoked when the property is reassigned to a different object v
     car property itself would be changed, which causes a change notification
     to be emitted.
 
+    \section1 Property Value Initialization Semantics
+
+    The QML syntax defines that curly braces on the right-hand-side of a
+    property value initialization assignment denote a binding assignment.
+    This can be confusing when initializing a \c var property, as empty curly
+    braces in JavaScript can denote either an expression block or an empty
+    object declaration.  If you wish to initialize a \c var property to an
+    empty object value, you should wrap the curly braces in parentheses.
+
+    For example:
+    \qml
+    Item {
+        property var first:  {}   // nothing = undefined
+        property var second: {{}} // empty expression block = undefined
+        property var third:  ({}) // empty object
+    }
+    \endqml
+
+    In the previous example, the \c first property is bound to an empty
+    expression, whose result is undefined.  The \c second property is bound to
+    an expression which contains a single, empty expression block ("{}"), which
+    similarly has an undefined result.  The \c third property is bound to an
+    expression which is evaluated as an empty object declaration, and thus the
+    property will be initialized with that empty object value.
+
+    Similarly, a colon in JavaScript can be either an object property value
+    assignment, or a code label.  Thus, initializing a var property with an
+    object declaration can also require parentheses:
+
+    \qml
+    Item {
+        property var first: { example: 'true' }    // example is interpreted as a label
+        property var second: ({ example: 'true' }) // example is interpreted as a property
+        property var third: { 'example': 'true' }  // example is interpreted as a property
+        Component.onCompleted: {
+            console.log(first.example) // prints 'undefined', as "first" was assigned a string
+            console.log(second.example) // prints 'true'
+            console.log(third.example) // prints 'true'
+        }
+    }
+    \endqml
+
     \section1 Using Scarce Resources with the var Type
 
     A \c var type property can also hold an image or pixmap.