Property: provide some hopefully exact documentation

Task-number: PYSIDE-1513
Pick-to: 5.15
Change-Id: I5817869aaf495f4005c4fda92d15fceafb15600a
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

1 files changed, 70 insertions, 3 deletions

diff --git a/sources/pyside6/doc/extras/QtCore.Property.rst b/sources/pyside6/doc/extras/QtCore.Property.rst
index ae61e44e4..5eb299f67 100644
--- a/sources/pyside6/doc/extras/QtCore.Property.rst
+++ b/sources/pyside6/doc/extras/QtCore.Property.rst
@@ -9,7 +9,9 @@ Detailed Description
 
 The Property function lets you declare properties that
 behave both as Qt and Python properties, and have their
-setters and getters defined as Python functions.
+getters and setters defined as Python functions.
+
+They are equivalent to the ``Q_PROPERTY`` macro in the `Qt Docs`_.
 
 Here is an example that illustrates how to use this
 function:
@@ -20,14 +22,14 @@ function:
     from PySide6.QtCore import QObject, Property
 
     class MyObject(QObject):
-        def __init__(self,startval=42):
+        def __init__(self, startval=42):
             QObject.__init__(self)
             self.ppval = startval
 
         def readPP(self):
             return self.ppval
 
-        def setPP(self,val):
+        def setPP(self, val):
             self.ppval = val
 
         pp = Property(int, readPP, setPP)
@@ -36,6 +38,68 @@ function:
     obj.pp = 47
     print(obj.pp)
 
+The full options for ``QtCore.Property`` can be found with ``QtCore.Property.__doc__``:
+
+.. code-block::
+
+   Property(self, type: type,
+            fget: Optional[Callable] = None,
+            fset: Optional[Callable] = None,
+            freset: Optional[Callable] = None,
+            fdel: Optional[Callable] = None,
+            doc: str = '', notify: Optional[Callable] = None,
+            designable: bool = True, scriptable: bool = True,
+            stored: bool = True, user: bool = False,
+            constant: bool = False, final: bool = False) -> PySide6.QtCore.Property
+
+Normally, only ``type``, ``fget``and ``fset`` are used.
+
+
+Properties compared with Python properties
+------------------------------------------
+
+``Python`` has property objects very similar to ``QtCore.Property``.
+Despite the fact that the latter has an extra ``freset`` function, the usage
+of properties is almost the same. The main difference is that ``QtCore.Property``
+requires a ``type`` parameter.
+
+In the above example, the following lines would be equivalent properties:
+
+.. code-block::
+
+        pp = QtCore.Property(int, readPP, setPP)    # PySide version
+        pp = property(readPP, setPP)                # Python version
+
+As you know from the `Python Docs`_, ``Python`` allows to break the property
+creation into multiple steps, using the decorator syntax. We can do this in
+``PySide`` as well:
+
+.. code-block::
+   :linenos:
+
+    from PySide6.QtCore import QObject, Property
+
+    class MyObject(QObject):
+        def __init__(self, startval=42):
+            QObject.__init__(self)
+            self.ppval = startval
+
+        @Property(int)
+        def pp(self):
+            return self.ppval
+
+        @pp.setter
+        def pp(self, val):
+            self.ppval = val
+
+    obj = MyObject()
+    obj.pp = 47
+    print(obj.pp)
+
+Please be careful here: The two ``Python`` functions have the same name, intentionally.
+This is needed to let ``Python`` know that these functions belong to the same property.
+
+
 Properties in QML expressions
 -----------------------------
 
@@ -61,3 +125,6 @@ example illustrating how to do this:
             pass
 
         name = Property(str, _name, notify=name_changed)
+
+.. _`Python Docs`:  https://docs.python.org/3/library/functions.html?highlight=property#property
+.. _`Qt Docs`:  https://doc.qt.io/qt-6/properties.html