1 files changed, 79 insertions, 13 deletions

diff --git a/sources/pyside6/doc/extras/QtCore.Property.rst b/sources/pyside6/doc/extras/QtCore.Property.rst
index ae61e44e4..9ed7de427 100644
--- a/sources/pyside6/doc/extras/QtCore.Property.rst
+++ b/sources/pyside6/doc/extras/QtCore.Property.rst
@@ -1,33 +1,32 @@
 .. currentmodule:: PySide6.QtCore
-.. _Property:
-
-Property
-********
+.. py:class:: Property
 
 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:
 
-.. code-block::
+.. code-block:: python
    :linenos:
 
     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 +35,71 @@ function:
     obj.pp = 47
     print(obj.pp)
 
+The full options for ``QtCore.Property`` can be found with ``QtCore.Property.__doc__``:
+
+.. code-block:: python
+
+    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:: python
+
+    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:: python
+   :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
 -----------------------------
 
@@ -43,12 +107,15 @@ If you are using properties of your objects in QML expressions,
 QML requires that the property changes are notified. Here is an
 example illustrating how to do this:
 
-.. code-block::
+.. code-block:: python
    :linenos:
 
     from PySide6.QtCore import QObject, Signal, Property
 
     class Person(QObject):
+
+        name_changed = Signal()
+
         def __init__(self, name):
             QObject.__init__(self)
             self._person_name = name
@@ -56,8 +123,7 @@ example illustrating how to do this:
         def _name(self):
             return self._person_name
 
-        @Signal
-        def name_changed(self):
-            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