path: root/doc
diff options
authorMarcelo Lira <>2009-11-13 19:04:38 -0300
committerMarcelo Lira <>2009-11-13 19:04:38 -0300
commitf659460ba56014b5e7d20a0f3d50b53619132add (patch)
tree8e83fa6f0709c20be3ee5ad2c1b21d99887a9987 /doc
parentcfae5701b16e057c992f0fadc7faf20dd3e09388 (diff)
updated code injection semantics documentation with guidelines on
how to call the wrapped C++ method/function
Diffstat (limited to 'doc')
1 files changed, 39 insertions, 4 deletions
diff --git a/doc/codeinjectionsemantics.rst b/doc/codeinjectionsemantics.rst
index 15ba426c..e1891188 100644
--- a/doc/codeinjectionsemantics.rst
+++ b/doc/codeinjectionsemantics.rst
@@ -123,16 +123,20 @@ Below is the example C++ class for whom wrapper code will be generated.
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 its
-contents with the injection spots marked.
+with the binding code. The next section will use a simplified version of the
+generated wrapper code with the injection spots marked with comments.
-Noteworthy Situations
+Noteworthy Cases
The type system description system gives the binding developer a lot of
flexibility, which is power, which comes with responsibility. Some modifications
to the wrapped API will not be complete without some code injection.
+Removing arguments and setting a default values for them
A simple case is when a function have one argument removed, as when the C++
method ``METHOD(ARG)`` is modified to be used from Python as ``METHOD()``;
of course the binding developer must provide some guidelines to the generator
@@ -140,12 +144,43 @@ on what to do to call it. The most common solution is to remove the argument and
set a default value for it at the same time, so the original C++ method could be
called without problems.
+Removing arguments and calling the method with your own hands
If the argument is removed and no default value is provided, the generator will
not write any call to the method and expect the ``modify-function - target/beginning``
code injection to call the original C++ method on its own terms. If even this
custom code is not provided the generator will put an ``#error`` clause to
prevent compilation of erroneus binding code.
+Calling the method with your own hands always!
+If your custom code to be injected contains a call to the wrapped C++ method,
+it surely means that you don't want the generator to write another call to the
+same method. As expected |project| will detect the user written call on the code
+injection and will not write its own call, but for this to work properly the
+binding developer must use the template variable ``%FUNCTION_NAME`` instead
+of writing the actual name of the wrapped method/function.
+In other words, use
+ .. code-block:: xml
+ <inject-code class="target" position="beginning | end">
+ %CPPSELF.originalMethodName();
+ </inject-code>
+instead of
+ .. code-block:: xml
+ <inject-code class="target" position="beginning | end">
+ </inject-code>
Code Injection for Functions/Methods