[PySide] [shiboken2] Object Ownership

[icfwm at gmx.net]

Hi,

I'm not sure if I miss some obvious piece of documentation, but after
reading https://doc.qt.io/qtforpython/shiboken2/ownership.html and also
https://doc.qt.io/qtforpython/shiboken2/typesystem_arguments.html#define-ownership
as well as the SampleBinding example, there are still open questions left...

One of the biggest unknowns here is the default ownership assumptions of
shiboken2. It is mentioned that there are some heuristics, but
unfortunately the documentation seems to be spread around the
aforementioned places, and so I'm not sure if I understood everything
correctly. I would like to give some examples in C++ code (assuming "A"
is a wrapped C++ class which is wrapped as <object-type>) and the
question is whether or not my assumptions are correct?

1.  A* createA(); // default ownership of return value: target language,
unless --enable-return-value-heuristic is given

2.  void doSomething(A* arg); // default ownership of argument: target
language

3.  void doSomething(A& arg); // default ownership of argument: target
language

4.  const A& getReference(); // what happens here? a copy of the result
is transferred to target ownership?

It seems that the default is that the target language owns all objects
passed around and transfer to c++ has to be made explicit in
typesystem.xml?

In the <define-ownership> tag documentation, for me it is completely
unclear what the class attribute means? I think the default is "target",
but what happens when you specify "native"?

In the object ownership documentation, it is mentioned that there is the
invalidate-after-use attribute, but this seems to be missing in the type
system reference. The given use case is completely unclear to me and it
would be good to have an example when this might be useful.

All in all, the object ownership documentation could be improved greatly
by giving some examples for the mentioned cases, not only in the xml
domain, but also in C++ domain.

Thanks for helping!
- icwfm -