From f40e0bcf674e03ce78751a799c2f0fb6f2b8b086 Mon Sep 17 00:00:00 2001
From: Ivan Solovev <ivan.solovev@qt.io>
Date: Fri, 22 Oct 2021 19:11:16 +0200
Subject: [PATCH] Extend documentation for bindable properties

Extend the general property system page with a section on how
to use bindable properties.
Add some cross-references to improve the user experience.

Task-number: QTBUG-97656
Pick-to: 6.2
Change-Id: I2520cdc168e3a8a66ea387e4ab717f4e0f969424
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
---
 src/corelib/doc/src/objectmodel/properties.qdoc | 17 +++++++++++++++++
 src/corelib/kernel/qproperty.cpp                | 13 +++++++++----
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc
index 8bc0c6041ab..e73bf0cebce 100644
--- a/src/corelib/doc/src/objectmodel/properties.qdoc
+++ b/src/corelib/doc/src/objectmodel/properties.qdoc
@@ -296,4 +296,21 @@
 
     Like other meta-data, class information is accessible at run-time
     through the meta-object; see QMetaObject::classInfo() for details.
+
+    \section1 Using Bindable Properties
+
+    Three different types can be used to implement bindable properties:
+    \list
+        \li \l QProperty
+        \li \l QObjectBindableProperty
+        \li \l QObjectComputedProperty.
+    \endlist
+    The first one is a general class for bindable properties. The latter
+    two can only be used inside a \l QObject.
+
+    For more information, including examples, see the classes mentioned above
+    and the general tips on implementing and using
+    \l {Qt Bindable Properties}{bindable properties}.
+
+    \sa {Qt Bindable Properties}
 */
diff --git a/src/corelib/kernel/qproperty.cpp b/src/corelib/kernel/qproperty.cpp
index f9df135d9c2..f8299b5d29b 100644
--- a/src/corelib/kernel/qproperty.cpp
+++ b/src/corelib/kernel/qproperty.cpp
@@ -1101,7 +1101,8 @@ QString QPropertyBindingError::description() const
 
    \ingroup tools
 
-   QBindable\<T\> helps to integrate Qt's traditional Q_PROPERTY with binding-enabled properties.
+   QBindable\<T\> helps to integrate Qt's traditional Q_PROPERTY with
+   \l {Qt Bindable Properties}{binding-enabled} properties.
    If a property is backed by a QProperty, QObjectBindableProperty or QObjectComputedProperty,
    you can add \c BINDABLE bindablePropertyName to the Q_PROPERTY
    declaration, where bindablePropertyName is a function returning an instance of QBindable
@@ -1112,7 +1113,8 @@ QString QPropertyBindingError::description() const
    \snippet code/src_corelib_kernel_qproperty.cpp 0
    \snippet code/src_corelib_kernel_qproperty.cpp 3
 
-   \sa QMetaProperty::isBindable, QProperty, QObjectBindableProperty
+   \sa QMetaProperty::isBindable, QProperty, QObjectBindableProperty,
+       QObjectComputedProperty, {Qt Bindable Properties}
 */
 
 /*!
@@ -1438,6 +1440,9 @@ QString QPropertyBindingError::description() const
   "NOTIFY xChanged" in the Q_PROPERTY macro as well as the last argument
   of the Q_OBJECT_BINDABLE_PROPERTY and Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS
   macros.
+
+  \sa Q_OBJECT_BINDABLE_PROPERTY, Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS, QProperty,
+      QObjectComputedProperty, {Qt's Property System}, {Qt Bindable Properties}
 */
 
 /*!
@@ -1592,8 +1597,8 @@ QString QPropertyBindingError::description() const
   QObjectComputedProperty is not suitable for use with a computation that depends
   on any input that might change without notice, such as the contents of a file.
 
-  \sa Q_OBJECT_COMPUTED_PROPERTY, QObjectBindableProperty, {Qt's Property System},
-      {Qt Bindable Properties}
+  \sa Q_OBJECT_COMPUTED_PROPERTY, QProperty, QObjectBindableProperty,
+      {Qt's Property System}, {Qt Bindable Properties}
 */
 
 /*!