From 273e7c5f4e73628494345b1c664508d3afe97ba3 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 5 Mar 2021 13:25:56 +0100 Subject: shiboken6: Brush up the code injection documentation Link from the code injection page to the type system variables. Link from conversion rule to templates. Modernize the code a bit. Change-Id: Ibc8e56a2e3313a0be50dc8bbc92f49a7afc775a2 Reviewed-by: Cristian Maureira-Fredes (cherry picked from commit 4972d8cf6ea55884e501c452f32f558ad24240ae) Reviewed-by: Qt Cherry-pick Bot --- sources/shiboken6/doc/typesystem_codeinjection.rst | 20 ++++++++++++-------- sources/shiboken6/doc/typesystem_conversionrule.rst | 3 +++ sources/shiboken6/doc/typesystem_variables.rst | 12 +++++++----- 3 files changed, 22 insertions(+), 13 deletions(-) diff --git a/sources/shiboken6/doc/typesystem_codeinjection.rst b/sources/shiboken6/doc/typesystem_codeinjection.rst index b0d5f3851..836609508 100644 --- a/sources/shiboken6/doc/typesystem_codeinjection.rst +++ b/sources/shiboken6/doc/typesystem_codeinjection.rst @@ -112,7 +112,8 @@ Below is the example C++ class for whom wrapper code will be generated. .. code-block:: c++ - class InjectCode { + class InjectCode + { public: InjectCode(); double overloadedMethod(int arg); @@ -124,6 +125,10 @@ From the C++ class, |project| will generate a ``injectcode_wrapper.cpp`` file with the binding code. The next section will use a simplified version of the generated wrapper code with the injection spots marked with comments. +There are a number of placeholders indicated by a percent sign ``%``, which +will be expanded when inserting the code. For a list, see +:ref:`typesystemvariables`. + Noteworthy Cases ---------------- @@ -196,7 +201,7 @@ class is polymorphic. int InjectCodeWrapper::virtualMethod(int arg) { - PyObject* method = BindingManager::instance().getOverride(this, "virtualMethod"); + PyObject *method = BindingManager::instance().getOverride(this, "virtualMethod"); if (!py_override) return this->InjectCode::virtualMethod(arg); @@ -228,10 +233,9 @@ own ``beginning`` and ``end`` code injections. .. code-block:: c++ - static PyObject* - PyInjectCode_overloadedMethod(PyObject* self, PyObject* arg) + static PyObject *PyInjectCode_overloadedMethod(PyObject *self, PyObject *arg) { - PyObject* py_result = 0; + PyObject* py_result{}; if (PyFloat_Check(arg)) { double cpp_arg0 = Shiboken::Converter::toCpp(arg); @@ -250,13 +254,13 @@ own ``beginning`` and ``end`` code injections. } else goto PyInjectCode_overloadedMethod_TypeError; if (PyErr_Occurred() || !py_result) - return 0; + return {}; return py_result; PyInjectCode_overloadedMethod_TypeError: PyErr_SetString(PyExc_TypeError, "'overloadedMethod()' called with wrong parameters."); - return 0; + return {}; } @@ -371,7 +375,7 @@ to prevent bad custom code to pass unnoticed. // INJECT-CODE: // Uses: do something before the module is created. - PyObject* module = Py_InitModule("MODULENAME", MODULENAME_methods); + PyObject *module = Py_InitModule("MODULENAME", MODULENAME_methods); (... initialization of wrapped classes, namespaces, functions and enums ...) diff --git a/sources/shiboken6/doc/typesystem_conversionrule.rst b/sources/shiboken6/doc/typesystem_conversionrule.rst index 27e7a72de..430c4e4b3 100644 --- a/sources/shiboken6/doc/typesystem_conversionrule.rst +++ b/sources/shiboken6/doc/typesystem_conversionrule.rst @@ -32,6 +32,9 @@ conversion-rule + The code can be inserted directly or via ``insert-template`` (see + :ref:`using-code-templates`). + The example above show the structure of a complete conversion rule. Each of the child tags comprising the conversion rule are described in their own sections below. diff --git a/sources/shiboken6/doc/typesystem_variables.rst b/sources/shiboken6/doc/typesystem_variables.rst index 73d4dd12c..3d4638253 100644 --- a/sources/shiboken6/doc/typesystem_variables.rst +++ b/sources/shiboken6/doc/typesystem_variables.rst @@ -1,3 +1,5 @@ +.. _typesystemvariables: + ********************* Type System Variables ********************* @@ -24,9 +26,9 @@ Variables .. _arg_number: -**%#** +**%** - Replaced by the name of a C++ argument in the position indicated by ``#``. + Replaced by the name of a C++ argument in the position indicated by ````. The argument counting starts with ``%1``, since ``%0`` represents the return variable name. If the number indicates a variable that was removed in the type system description, but there is a default value for it, this value will @@ -214,13 +216,13 @@ Variables .. _pyarg: -**%PYARG_#** +**%PYARG_** - Similar to ``%#``, but is replaced by the Python arguments (PyObjects) + Similar to ``%``, but is replaced by the Python arguments (PyObjects) received by the Python wrapper method. If used in the context of a native code injection, i.e. in a virtual method - override, ``%PYARG_#`` will be translated to one item of the Python tuple + override, ``%PYARG_`` will be translated to one item of the Python tuple holding the arguments that should be passed to the Python override for this virtual method. -- cgit v1.2.3