Doc: Describe property bindings in terms of relationships

- This patch aims to help readers think about bindings more
  "declaratively" by introducing a new (albeit very leaky) level of
  abstraction: Treat bindings as finitary relations, rather than mere
  JavaScript expressions.

- In essence, property bindings are for describing relationships between
  properties. The fact that the QML engine reactively updates a
  property's value when its dependencies change, and the fact that
  arbitrarily complex expressions are valid bindings, are simply
  implementation details.

- Discourage the use of side effects in property bindings. They are not
  essential for the main purpose of property bindings, they break the
  finitary relation model, and their use can reduce code
  readability/maintainability/toolability.

- Discourage complex property bindings for similar reasons.

Change-Id: I5a0a03bd02768d4c504797a0f86569f3ac066e96
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

2 files changed, 21 insertions, 24 deletions

diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc
index c33daf7acc..79c11b3ac5 100644
--- a/src/qml/doc/src/javascript/expressions.qdoc
+++ b/src/qml/doc/src/javascript/expressions.qdoc
@@ -57,30 +57,28 @@ QML \l{QML Object Types}{object types} defined in \l{QML Documents}
 {QML documents} can make use of JavaScript expressions which implement program
 logic.  There are four ways that JavaScript can be used in a QML document:
 
-\list
-  \li \l{Property Attributes}{properties} can be
-      assigned \l{Property Binding}{bindings} which are defined with
-      JavaScript expressions, and which are automatically evaluated by the
-      \l{QQmlEngine}{QML engine} when any properties accessed in the binding
-      change, in order to ensure always-up-to-date property values.  Binding
-      expressions can also perform function evaluation as an explicit side
-      effect
-  \li \l{Signal Attributes}{signal handlers} can be defined
+\list 1
+  \li Relationships between \l{Property Attributes}{properties} are described
+      using JavaScript expressions in \l{Property Binding}{property bindings}.
+      When any of a property's \e dependencies change, the property is
+      automatically updated too, according to the specified relationship.
+  \li \l{Signal Attributes}{Signal handlers} can be defined
       which are automatically evaluated when the object emits the associated
-      signal
-  \li \l{Method Attributes}{custom methods} can be defined
-      in QML files as JavaScript functions
+      signal.
+  \li \l{Method Attributes}{Custom methods} can be defined
+      in QML files as JavaScript functions.
   \li JavaScript files providing functions and variables can be
       \l{Importing JavaScript Resources in QML}{imported} in a QML
-      document
+      document.
 \endlist
 
 
 
 \section2 Property Bindings
 
-During startup, the QML engine will set up and initialize the property
-bindings. The JavaScript conditional operator is a valid property binding.
+In the following example, the \l Rectangle's \c color depends on the
+\l MouseArea's \c pressed property. This relationship is described using a
+conditional expression:
 
 \qml
 import QtQuick 2.0
@@ -100,7 +98,9 @@ Rectangle {
 
 In fact, any JavaScript expression (no matter how complex) may be used in a
 property binding definition, as long as the result of the expression is a
-value whose type can be assigned to the property.
+value whose type can be assigned to the property.  This includes side effects.
+However, complex bindings and side effects are discouraged because they can
+reduce the performance, readability, and maintainability of the code.
 
 There are two ways to define a property binding: the first (and most common)
 is, as previously shown, in a \l{QML Object Attributes#Value Assignment on Initialization}
diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc
index 40602b5017..f341816201 100644
--- a/src/qml/doc/src/javascript/topic.qdoc
+++ b/src/qml/doc/src/javascript/topic.qdoc
@@ -38,14 +38,11 @@ JavaScript to quickly develop both user-interfaces and application logic.
 
 \section1 JavaScript Expressions
 
-QML has a deep JavaScript integration, and allows
-\l{Signal Attributes}{signal handlers}
-and \l{Method Attributes}{methods}
-to be defined in JavaScript.  One of the other fundamental concepts of QML is
-the ability to bind property values to the result of complex expressions which
-can include properties from other objects. These
-\l{Property Binding}{property bindings}
-are JavaScript expressions.
+QML has a deep JavaScript integration, and allows \l{Signal Attributes}
+{signal handlers} and \l{Method Attributes}{methods} to be defined in JavaScript.
+Another core feature of QML is the ability to specify and enforce relationships
+between object properties using \l{Property Binding}{property bindings}, which
+are also defined using JavaScript.
 
 See the documentation page titled
 \l{qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents}