Document requirements for getters and setters of bindable properties

Getters and setters of bindable properties have to be carefully
written to avoid several problems. This patch adds documentation
for this.

Task-number: QTBUG-89505
Task-number: QTBUG-90511
Change-Id: Ib25590b3d8d95c490d9555c0f258f48cb6cfe4a9
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

src/corelib/doc/src/objectmodel/bindableproperties.qdoc

@@ -86,6 +86,36 @@
     is an integer and folded into the string value using conversion to integer, but
     the dependency is fully tracked.
 
+    \section1 Bindable Property Getters and Setters
+
+    When a class has a bindable property, either using QProperty
+    or QObjectBindableProperty, special care has to be taken when formulating
+    getters and setters for that property.
+
+    \section2 Bindable Property Getters
+
+    To ensure proper operation of the automatic dependency-tracking system,
+    every possible code path in a getter needs to read from the underlying
+    property object.
+    In addition, the property must not be written inside the getter.
+    Design patterns which recompute or refresh anything in the getter
+    are not compatible with bindable properties.
+
+    It is therefore recommended to only use trivial getters with bindable properties.
+
+    \section2 Bindable Property Setters
+
+    To ensure proper operation of the automatic dependency-tracking system,
+    every possible code path in a setter needs to write to the underlying
+    property object, even if the value did not change.
+
+    Any other code in a setter has a high propability of being incorrect.
+    Any code doing updates based on the new value is most likely a bug,
+    as this code won't be executed when the property is changed
+    through a binding.
+
+    It is therefore recommended to only use trivial setters with bindable properties.
+
     \section1 Tracking Bindable Properties
 
     Sometimes the relationships between properties cannot be expressed using

src/corelib/kernel/qproperty.cpp

@@ -1114,14 +1114,16 @@ QString QPropertyBindingError::description() const
   QObjectBindableProperty is a generic container that holds an
   instance of T and behaves mostly like \l QProperty.
   It is one of the classes implementing \l {Qt Bindable Properties}.
-  The extra template
-  parameters are used to identify the surrounding class and a member function of
-  that class. The member function will be called whenever the value held by the
-  property changes.
+  Unlike QProperty, it stores its management data structure in
+  the sourrounding QObject.
+  The extra template parameters are used to identify the surrounding
+  class and a member function of that class acting as a change handler.
 
   You can use QObjectBindableProperty to add binding support to code that uses Q_PROPERTY.
-  The getter and setter methods are easy to adapt for accessing a \l QObjectBindableProperty
-  rather than the plain value. In order to invoke the change signal on property changes, use
+  The getter and setter methods must be adapted carefully according to the
+  rules described in \l {Bindable Property Getters and Setters}.
+
+  In order to invoke the change signal on property changes, use
   QObjectBindableProperty and pass the change signal as a callback.
 
   QObjectBindableProperty is usually not used directly, instead an instance of it is created by