shiboken6: Improve documentation on ownership

Change-Id: Ie2c8b069d78315736140ce8857e3f60f96b018e0
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 0d7a8f100836608297286f02138f5c1c10992e31)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 68 insertions, 13 deletions

diff --git a/sources/shiboken6/doc/shibokenmodule.rst b/sources/shiboken6/doc/shibokenmodule.rst
index 150998ccd..d6bb12653 100644
--- a/sources/shiboken6/doc/shibokenmodule.rst
+++ b/sources/shiboken6/doc/shibokenmodule.rst
@@ -1,7 +1,9 @@
-.. module:: shiboken
+. module:: shiboken
 
 .. |maya| unicode:: Maya U+2122
 
+.. _shiboken-module:
+
 Shiboken module
 ***************
 
diff --git a/sources/shiboken6/doc/typesystem_ownership.rst b/sources/shiboken6/doc/typesystem_ownership.rst
index 71ddc8c71..f9e705b4f 100644
--- a/sources/shiboken6/doc/typesystem_ownership.rst
+++ b/sources/shiboken6/doc/typesystem_ownership.rst
@@ -26,6 +26,11 @@ C++ object is already deleted, or maybe the C++ object should not be freed after
 the Python wrapper go out of scope and die, because C++ is already taking care of
 the wrapped instance.
 
+This is not a concern for value types specified by :ref:`value-type`, which can
+be freely created, copied and destroyed, however object types specified by
+:ref:`object-type` pointing to C++ instances with life cycle constraints
+may require attention.
+
 In order to handle this, you should tell the
 generator whether the instance's ownership belongs to the binding or
 to the C++ Library. When belonging to the binding, we are sure that the C++ object
@@ -33,6 +38,14 @@ won't be deleted by C++ code and we can call the C++ destructor when the refcoun
 reaches 0. Otherwise, instances owned by C++ code can be destroyed arbitrarily,
 without notifying the Python wrapper of its destruction.
 
+By default, objects created in Python have ownership. A relevant case are
+return values of virtual factory methods reimplemented in Python
+(C++ Wrapper Code) which pass the bindings code. Objects obtained from C++
+(for example, ``QGuiApplication::clipoard()``) do not have ownership.
+
+The :ref:`shiboken-module` module provides the ``dump()`` utility function,
+which prints the relevant information for an object.
+
 Invalidating objects
 ====================
 
@@ -123,7 +136,17 @@ Return value heuristics
     When enabled, object returned as pointer in C++ will become child of the object on which the method
     was called.
 
-    To activate this heuristic, use the :ref:`--enable-return-value-heuristic <return-heuristic>`
+    To activate this heuristic, use the command line switch
+    :ref:`--enable-return-value-heuristic <return-heuristic>`.
+
+    To disable this heuristic for specific cases, specify ``default`` as
+    ownership:
+
+    .. code-block:: xml
+
+        <modify-argument index="0">
+            <define-ownership class="target" owner="default" />
+        </modify-argument>
 
 Common pitfalls
 ===============
@@ -158,11 +181,14 @@ Not saving unowned objects references
 Ownership Management in  the Typesystem
 =======================================
 
-For the possible values of the ``class`` attribute, see
-:ref:`codegenerationterminology`.
+Python Wrapper Code
+-------------------
+
+For this code, the ``class`` attribute takes the value ``target``
+(see :ref:`codegenerationterminology`).
 
 Ownership transfer from C++ to target
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     When an object currently owned by C++ has its ownership transferred
     back to the target language, the binding can know for sure when the object will be deleted and
@@ -175,8 +201,11 @@ Ownership transfer from C++ to target
             <define-ownership class="target" owner="target" />
         </modify-argument>
 
+    A typical use case would be returning an object allocated in C++, for
+    example from ``clone()`` or other factory methods.
+
 Ownership transfer from target to C++
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     In the opposite direction, when an object ownership is transferred from the target language
     to C++, the native code takes full control of the object life and you don't
@@ -195,9 +224,13 @@ Ownership transfer from target to C++
             <define-ownership class="target" owner="c++" />
         </modify-argument>
 
+    Use cases would be an returning a member object by pointer
+    or passing an object by pointer into a function where the class
+    takes ownership, for example
+    ``QNetworkAccessManager::setCookieJar(QNetworkCookieJar *)``.
 
 Parent-child relationship
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One special type of relationship is the parent-child. When an object is called
 the parent of another object (the child), the former is in charge of deleting its
@@ -210,7 +243,7 @@ classes, creating "trees" of instances.
     .. code-block:: xml
 
         <modify-argument index="this">
-            <parent index="1" action="add">
+            <parent index="1" action="add"/>
         </modify-argument>
 
 In this example, the instance with the method that is being invoked (indicated by 'index="this"' on
@@ -222,14 +255,34 @@ See `Object Trees and Object Ownership in Qt`_.
 
 .. _`Object Trees and Object Ownership in Qt`: http://doc.qt.io/qt-6/objecttrees.html
 
+C++ Wrapper Code
+----------------
+
+For this code, the ``class`` attribute takes the value ``native``. The
+modifications affect code called from within C++, typically when calling
+virtual C++ methods reimplemented in Python
+(see :ref:`codegenerationterminology`).
+
+Return values of virtual functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ownership of C++ objects returned by pointer should be set to ``c++`` to
+prevent them from being deleted by Python, since objects created
+in Python have ownership by default.
+
+Ownership transfers specified for other arguments do not have any effect.
+
 .. _invalidationafteruse:
 
 Invalidation after use
-----------------------
-
-Sometimes an object is created as a virtual method call argument and destroyed after the
-call returned. In this case, you should use the ``invalidate-after-use`` attribute in the
-``modify-argument`` tag to mark the wrapper as invalid right after the virtual method returns.
+^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes an object is created in C++ and passed as a virtual method call
+argument and destroyed after the call returned
+(see :ref:`ownership-virt-method`).
+In this case, you should use the ``invalidate-after-use`` attribute in the
+:ref:`modify-argument` tag to mark the wrapper as invalid right after the
+virtual method returns.
 
     .. code-block:: xml