Document difference between property binding and assignment

Task-number: QTBUG-12629

2 files changed, 62 insertions, 5 deletions

diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index 18da3d2..d290690 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -173,6 +173,40 @@ handler to execute at startup, they are run sequentially in an undefined order.
 Likewise, the \l {Component::onDestruction} attached property is triggered on
 component destruction.
 
+
+\section1 Property Assignment vs Property Binding
+
+When working with both QML and JavaScript, it is important to differentiate between
+QML \l {Property Binding} and JavaScript value assignment. In QML, a property 
+binding is created using the \e {property: value} syntax:
+
+\code
+Rectangle {
+    width: otherItem.width
+}
+\endcode
+
+The \c width of the above \l Rectangle is updated whenever \c otherItem.width changes. On the other
+hand, take the following JavaScript code snippet, that runs when the \l Rectangle is created:
+
+\code
+Rectangle {
+
+    Component.onCompleted: {
+        width = otherItem.width;
+    }
+}
+\endcode
+
+The \c width of this \l Rectangle is \e assigned the value of \c otherItem.width using the
+\e {property = value} syntax in JavaScript. Unlike the QML \e {property: value} syntax, this
+does not invoke QML property binding; the \c rectangle.width property is set to the value
+of \c otherItem.width at the time of the assignment and will not be updated if that value
+changes.
+
+See \l {Property Binding} for more information.
+
+
 \section1 QML JavaScript Restrictions
 
 QML executes standard JavaScript code, with the following restrictions:
diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
index 552b9e4..314bf67 100644
--- a/doc/src/declarative/propertybinding.qdoc
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -94,10 +94,29 @@ Rectangle {
 }
 \endcode
 
-Imperatively assigning a value directly to a property will also implicitly remove a binding
-on a property.  A property can only have one value at a time, and if code explicitly sets
-this value the binding must be removed.  The \l Rectangle in the example below will have
-a width of 13, regardless of the otherItem's width.
+
+\section1 Effects of Property Assignment in JavaScript
+
+Assigning a property value from JavaScript does \e not create a property binding.
+For example:
+
+\code
+Rectangle {
+
+    Component.onCompleted: {
+        width = otherItem.width;
+    }
+}
+\endcode
+
+Instead of creating a property binding, this simply sets the \c width of the \l Rectangle
+to the value of \c other.width at the time the JavaScript code is invoked.  See 
+\l {Property Assignment vs Property Binding} for more details.
+
+Also note that assigning a value to a property that is currently bound will remove the binding.
+A property can only have one value at a time, and if any code explicitly sets
+this value, the binding is removed.  The \l Rectangle in the example below will have
+a width of 13, regardless of the \c otherItem's width.
 
 \code
 Rectangle {
@@ -109,7 +128,9 @@ Rectangle {
 }
 \endcode
 
-There is no way to create a property binding directly from imperative JavaScript code.
+There is no way to create a property binding directly from imperative JavaScript code,
+although it is possible to set up a \l Binding object (shown below).
+
 
 \section1 Binding Element
 
@@ -126,5 +147,7 @@ Binding {
     value: slider.value
 }
 \endqml
+
+
 */