Add documentation how to formulate a property binding

To correctly formulate a property binding, some rules must be
followed. So far, these rules are not documented. This patch
adds such documentation.

Task-number: QTBUG-90511
Change-Id: Ibb509ea9098212c95f03433feb1f1aac751c4b2e
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 38 insertions, 0 deletions

diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
index b0241a3d4f..6e63481c14 100644
--- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
+++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
@@ -169,6 +169,44 @@
     Here, code triggered in change handlers might use the circle, while it has
     the new radius, but still the old area.
 
+    \section1 Formulating a Property Binding
+
+    Any C++ expression evaluating to the correct type can be used as a binding
+    expression and be given to the setBinding() method. However, to formulate
+    a correct binding, some rules must be followed.
+
+    Dependency tracking only works on bindable properties. It's the developer's
+    responsibility to ensure that all properties used in the binding expression
+    are bindable properties. When non-bindable properties are used in a binding
+    expression, changes to those properties do not trigger updates to the bound
+    property. No warning or error is generated either at compile-time or at run-time.
+    The bound property will be updated only when bindable properties used in the
+    binding expression are changed.
+    Non-bindable properties might be used in a binding if it's possible
+    to ensure that markDirty is called on the property being bound on each
+    change of the non-bindable dependency.
+
+    The bound property might evaluate its binding several times during its lifetime.
+    The developer must make sure that all objects used in the binding expression
+    live longer than the binding.
+
+    The bindable property system is not thread-safe. Properties used in the binding
+    expression on one thread must not be read or modified by any other thread.
+    An object of a QObject-derived class which has a property with a binding must
+    not be moved to a different thread.
+    Also, an object of a QObject-derived class which has a property which is used
+    in a binding must not be moved to a different thread. In this context, it's
+    irrelevant whether it's used in a binding of a property in the same object
+    or in a binding of a property in another object.
+
+    The binding expression should not read from the property it's a binding for. Otherwise,
+    an evaluation loop exists.
+
+    The binding expression must not write to the property it's a binding for.
+
+    Functions used as bindings as well as all code which is called inside a binding
+    must not co_await. Doing so can confuse the property system's tracking of dependencies.
+
     \section1 Tracking Bindable Properties
 
     Sometimes the relationships between properties cannot be expressed using