diff options
| author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2024-09-02 13:30:18 +0200 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2024-09-03 07:39:16 +0200 |
| commit | 145b665575b70932a31dfd40a4cf7061772e694c (patch) | |
| tree | fc3c56d6e818d9b94f0bf8df4c67c597e87a6b79 | |
| parent | 66986fdcd4b2fe24704d0710cc60649753f1d8a2 (diff) | |
shiboken6: Restructure documentation on modifying functions
Fold typesystem_modify_function.rst, which had little content, into
typesystem_arguments.rst and group the modifications with
sub-headings. Fix wording and remove unimplemented attributes.
Pick-to: 6.7
Task-number: PYSIDE-1112
Change-Id: I6dff6320e11589d1f61d1ebac7cc36bf7217fdf4
Reviewed-by: Shyamnath Premnadh <Shyamnath.Premnadh@qt.io>
| -rw-r--r-- | sources/shiboken6/doc/typesystem.rst | 3 | ||||
| -rw-r--r-- | sources/shiboken6/doc/typesystem_arguments.rst | 223 | ||||
| -rw-r--r-- | sources/shiboken6/doc/typesystem_manipulating_objects.rst | 4 | ||||
| -rw-r--r-- | sources/shiboken6/doc/typesystem_modify_function.rst | 44 |
4 files changed, 140 insertions, 134 deletions
diff --git a/sources/shiboken6/doc/typesystem.rst b/sources/shiboken6/doc/typesystem.rst index 26f929801..37a4a661b 100644 --- a/sources/shiboken6/doc/typesystem.rst +++ b/sources/shiboken6/doc/typesystem.rst @@ -38,12 +38,11 @@ Modifying types .. toctree:: :maxdepth: 1 - typesystem_arguments.rst + Function argument modifications <typesystem_arguments.rst> typesystem_codeinjection.rst typesystem_converters.rst typesystem_containers.rst typesystem_templates.rst - typesystem_modify_function.rst typesystem_manipulating_objects.rst typesystem_conversionrule.rst typesystem_documentation.rst diff --git a/sources/shiboken6/doc/typesystem_arguments.rst b/sources/shiboken6/doc/typesystem_arguments.rst index d950b6c32..c3ad1c707 100644 --- a/sources/shiboken6/doc/typesystem_arguments.rst +++ b/sources/shiboken6/doc/typesystem_arguments.rst @@ -1,56 +1,45 @@ -.. _modifying-arguments: +.. _modify-argument: -Modifying Arguments -------------------- +modify-argument +--------------- -.. _conversionrule-on-arguments: - -conversion-rule -^^^^^^^^^^^^^^^ - -The ``conversion-rule`` node allows you to write customized code to convert -the given argument between the target language and C++. -It is then a child of the :ref:`modify-argument` node: +Function argument modifications consist of a list of ``modify-argument`` nodes +contained in :ref:`modify-function`, :ref:`add-function` or +:ref:`declare-function` nodes. Nested :ref:`remove-argument`, +:ref:`replace-default-expression`, :ref:`remove-default-expression`, +:ref:`replace-type`, :ref:`reference-count` and :ref:`define-ownership` +nodes specify the details of the modification. .. code-block:: xml - <modify-argument index="2"> - <!-- for the second argument of the function --> - <conversion-rule class="target | native"> - // the code - </conversion-rule> - </modify-argument> + <modify-function> + <modify-argument index="return | this | 1 ..." rename="..." + invalidate-after-use = "true | false" pyi-type="..."> + // modifications + </modify-argument> + </modify-function> -The ``class`` attribute accepts one of the following values to define the -conversion direction to be either ``target-to-native`` or ``native-to-target``: +Set the ``index`` attribute to "1" for the first argument, "2" for the second +one and so on. Alternatively, set it to "return" or "this" if you want to +modify the function's return value or the object the function is called upon, +respectively. -* ``native``: Defines the conversion direction to be ``target-to-native``. - It is similar to the existing ``<target-to-native>`` element. - See :ref:`Conversion Rule Tag <conversion-rule-tag>` for more information. - -* ``target``: Defines the conversion direction to be ``native-to-target``. - It is similar to the existing ``<native-to-target>`` element. - See :ref:`Conversion Rule Tag <conversion-rule-tag>` for more information. - -This node is typically used in combination with the :ref:`replace-type` and -:ref:`remove-argument` nodes. The given code is used instead of the generator's -conversion code. +The optional ``rename`` attribute is used to rename a argument and use this +new name in the generated code. This attribute can be used to enable the usage +of ``keyword arguments``. -Writing %N in the code (where N is a number), will insert the name of the -nth argument. Alternatively, %in and %out which will be replaced with the -name of the conversion's input and output variable, respectively. Note the -output variable must be declared explicitly, for example: - -.. code-block:: xml - - <conversion-rule class="native"> - bool %out = (bool) %in; - </conversion-rule> +The optional ``pyi-type`` attribute specifies the type to appear in the +signature strings and ``.pyi`` files. The type string is determined by +checking this attribute value, the :ref:`replace-type` modification and +the C++ type. The attribute can be used for example to enclose +a pointer return value within ``Optional[]`` to indicate that ``None`` +can occur. -.. note:: +For the optional ``invalidate-after-use`` attribute, +see :ref:`invalidationafteruse` . - You can also use the ``conversion-rule`` node to specify - :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-tag>`. +Naming, type, default value modifications ++++++++++++++++++++++++++++++++++++++++++ .. _remove-argument: @@ -130,6 +119,9 @@ If the new type is a class, the ``modified-type`` attribute must be set to the fully qualified name (including name of the package as well as the class name). +Ownership/Reference modifications ++++++++++++++++++++++++++++++++++ + .. _define-ownership: define-ownership @@ -138,25 +130,26 @@ define-ownership The ``define-ownership`` tag indicates that the function changes the ownership rules of the argument object, and it is a child of the :ref:`modify-argument` node. + +.. code-block:: xml + + <modify-argument> + <define-ownership class="target | native" + owner="target | c++ | default" /> + </modify-argument> + The ``class`` attribute specifies the class of function where to inject the ownership altering code (see :ref:`codegenerationterminology`). The ``owner`` attribute specifies the new ownership of the object. It accepts the following values: * target: the target language will assume full ownership of the object. - The native resources will be deleted when the target language - object is finalized. + The native resources will be deleted when the target language + object is finalized. * c++: The native code assumes full ownership of the object. The target - language object will not be garbage collected. + language object will not be garbage collected. * default: The object will get default ownership, depending on how it - was created. - -.. code-block:: xml - - <modify-argument> - <define-ownership class="target | native" - owner="target | c++ | default" /> - </modify-argument> + was created. .. _reference-count: @@ -166,47 +159,40 @@ reference-count The ``reference-count`` tag dictates how an argument should be handled by the target language reference counting system (if there is any), it also indicates the kind of relationship the class owning the function being modified has with -the argument. It is a child of the :ref:`modify-argument` node. -For instance, in a model/view relation a view receiving a model -as argument for a **setModel** method should increment the model's reference -counting, since the model should be kept alive as much as the view lives. -Remember that out hypothetical view could not become parent of the model, -since the said model could be used by other views as well. -The ``action`` attribute specifies what should be done to the argument -reference counting when the modified method is called. It accepts the -following values: - -* add: increments the argument reference counter. -* add-all: increments the reference counter for each item in a collection. -* remove: decrements the argument reference counter. -* set: will assign the argument to the variable containing the reference. -* ignore: does nothing with the argument reference counter - (sounds worthless, but could be used in situations - where the reference counter increase is mandatory - by default). +the argument (represented as lists of referred-to objects stored in the +owner class). It is a child of the :ref:`modify-argument` node. .. code-block:: xml <modify-argument> - <reference-count action="add|add-all|remove|set|ignore" variable-name="..." /> + <reference-count action="add|remove|set|ignore" variable-name="..." /> </modify-argument> +The ``action`` attribute specifies what should be done to the argument +reference counting when the modified method is called. It accepts the +following values: -The variable-name attribute specifies the name used for the variable that -holds the reference(s). - -.. _replace-value: - -replace-value -^^^^^^^^^^^^^ - -The ``replace-value`` attribute lets you replace the return statement of a -function with a fixed string. This attribute can only be used for the -argument at ``index`` 0, which is always the function's return value. +* add: Adds the argument to the list of previous argument values stored + under this ``variable-name`` or function signature and increments + the argument reference counter. +* remove: Decrements the argument reference counter and removes it from + the list of argument values stored under this ``variable-name`` + or function signature. +* set: Decreases the reference count of the previously stored argument values + under this ``variable-name`` or function signature and removes them. + Stores the argument and increments the argument reference counter. +* ignore: does nothing with the argument reference counter + (sounds worthless, but could be used in situations + where the reference counter increase is mandatory by default). -.. code-block:: xml +The ``variable-name`` attribute specifies the name used for the variable that +holds the reference(s). It defaults to the function signature. - <modify-argument index="0" replace-value="this"/> +For instance, in a model/view relation, a view receiving a model +as argument for a **setModel()** method should increment the model's reference +counting, since the model should be kept alive as long as the view lives. +Remember that our hypothetical view cannot become a :ref:`parent` of the +model, since the said model could be used by other views as well. .. _parent: @@ -227,3 +213,68 @@ It is a child of the :ref:`modify-argument` node. In the ``index`` argument you must specify the parent argument. The action *add* creates a parent link between objects, while *remove* will undo the parentage relationship. + +Other modifications ++++++++++++++++++++ + +.. _conversionrule-on-arguments: + +conversion-rule +^^^^^^^^^^^^^^^ + +The ``conversion-rule`` node allows you to write customized code to convert +the given argument between the target language and C++. +It is then a child of the :ref:`modify-argument` node: + +.. code-block:: xml + + <modify-argument index="2"> + <!-- for the second argument of the function --> + <conversion-rule class="target | native"> + // the code + </conversion-rule> + </modify-argument> + +The ``class`` attribute accepts one of the following values to define the +conversion direction to be either ``target-to-native`` or ``native-to-target``: + +* ``native``: Defines the conversion direction to be ``target-to-native``. + It is similar to the existing ``<target-to-native>`` element. + See :ref:`Conversion Rule Tag <conversion-rule-tag>` for more information. + +* ``target``: Defines the conversion direction to be ``native-to-target``. + It is similar to the existing ``<native-to-target>`` element. + See :ref:`Conversion Rule Tag <conversion-rule-tag>` for more information. + +This node is typically used in combination with the :ref:`replace-type` and +:ref:`remove-argument` nodes. The given code is used instead of the generator's +conversion code. + +Writing %N in the code (where N is a number), will insert the name of the +nth argument. Alternatively, %in and %out which will be replaced with the +name of the conversion's input and output variable, respectively. Note the +output variable must be declared explicitly, for example: + +.. code-block:: xml + + <conversion-rule class="native"> + bool %out = (bool) %in; + </conversion-rule> + +.. note:: + + You can also use the ``conversion-rule`` node to specify + :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-tag>`. + +.. _replace-value: + +replace-value +^^^^^^^^^^^^^ + +The ``replace-value`` attribute lets you replace the return statement of a +function with a fixed string. This attribute can only be used for the +argument at ``index`` 0, which is always the function's return value. + +.. code-block:: xml + + <modify-argument index="0" replace-value="this"/> diff --git a/sources/shiboken6/doc/typesystem_manipulating_objects.rst b/sources/shiboken6/doc/typesystem_manipulating_objects.rst index 7d7074878..b63a4710a 100644 --- a/sources/shiboken6/doc/typesystem_manipulating_objects.rst +++ b/sources/shiboken6/doc/typesystem_manipulating_objects.rst @@ -154,8 +154,8 @@ modify-function The ``modify-function`` node allows you to modify a given C++ function when mapping it onto the target language, and it is a child of a :ref:`function`, :ref:`namespace`, :ref:`object-type` or a :ref:`value-type` node. -Use the :ref:`modify-argument` node to specify which argument the -modification affects. +Nested :ref:`modify-argument` nodes can used to modify arguments +or return values. .. code-block:: xml diff --git a/sources/shiboken6/doc/typesystem_modify_function.rst b/sources/shiboken6/doc/typesystem_modify_function.rst deleted file mode 100644 index 54ac6412f..000000000 --- a/sources/shiboken6/doc/typesystem_modify_function.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _modifying-functions: - -Modifying Functions -------------------- - -.. _modify-argument: - -modify-argument -^^^^^^^^^^^^^^^ - -Function modifications consist of a list of ``modify-argument`` nodes -contained in :ref:`modify-function`, :ref:`add-function` or -:ref:`declare-function` nodes. Use the :ref:`remove-argument`, -:ref:`replace-default-expression`, :ref:`remove-default-expression`, -:ref:`replace-type`, :ref:`reference-count` and :ref:`define-ownership` -nodes to specify the details of the modification. - -.. code-block:: xml - - <modify-function> - <modify-argument index="return | this | 1 ..." rename="..." - invalidate-after-use = "true | false" pyi-type="..."> - // modifications - </modify-argument> - </modify-function> - -Set the ``index`` attribute to "1" for the first argument, "2" for the second -one and so on. Alternatively, set it to "return" or "this" if you want to -modify the function's return value or the object the function is called upon, -respectively. - -The optional ``rename`` attribute is used to rename a argument and use this -new name in the generated code. This attribute can be used to enable the usage -of ``keyword arguments``. - -The optional ``pyi-type`` attribute specifies the type to appear in the -signature strings and ``.pyi`` files. The type string is determined by -checking this attribute value, the :ref:`replace-type` modification and -the C++ type. The attribute can be used for example to enclose -a pointer return value within ``Optional[]`` to indicate that ``None`` -can occur. - -For the optional ``invalidate-after-use`` attribute, -see :ref:`invalidationafteruse` . |