Shiboken documentation updated with type system variables information

Reviewed by Hugo Lima <hugo.lima@openbossa.org>

4 files changed, 111 insertions, 4 deletions

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index ef2e9a610..2accb5d2e 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -11,12 +11,14 @@
     <td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
          <span class="linkdescr">for a complete overview</span></p>
+     <p class="biglink"><a class="biglink" href="{{ pathto("typesystemvariables") }}">Type System Variables</a><br/>
+         <span class="linkdescr">describes the type system variables that could be used in user custom code</span></p>
      <p class="biglink"><a class="biglink" href="{{ pathto("codeinjectionsemantics") }}">Code Injection Semantics</a><br/>
          <span class="linkdescr">explains how custom code injection is interpreted by {{ project }}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/>
-         <span class="linkdescr">support for python sequence protocol</span></p>
     </td>
     <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/>
+         <span class="linkdescr">support for python sequence protocol</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("compiling") }}">Compiling/Installing</a><br/>
          <span class="linkdescr">how to compile and install {{ project }}</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQ</a><br/>
diff --git a/doc/contents.rst b/doc/contents.rst
index 4e0a5e9e5..f6735ee83 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -5,6 +5,7 @@ Table of contents
     :maxdepth: 3
 
     faq.rst
+    typesystemvariables.rst
     codeinjectionsemantics.rst
     sequenceprotocol.rst
     compiling.rst
diff --git a/doc/sequenceprotocol.rst b/doc/sequenceprotocol.rst
index 2ac48588e..587c0f95b 100644
--- a/doc/sequenceprotocol.rst
+++ b/doc/sequenceprotocol.rst
@@ -17,8 +17,7 @@ The special function names are:
 
 You just need to inform the function name to the add-function tag, without any parameter or return type information, when you do it, |project| will create a C function with parameters and return type definied by the table above.
 
-The function needs to follow the same semantics of the *CPython equivalent* function, the only way to do it is using the inject-code tag.
+The function needs to follow the same semantics of the *CPython equivalent* function, the only way to do it is using the :doc:`inject-code <codeinjectionsemantics>` tag.
 
 A concrete exemple how to add sequence protocol support to a class can be found on shiboken tests, more precisely in the definition of the Str class in ``tests/samplebinding/typesystem_sample.xml``.
 
-
diff --git a/doc/typesystemvariables.rst b/doc/typesystemvariables.rst
new file mode 100644
index 000000000..63177569d
--- /dev/null
+++ b/doc/typesystemvariables.rst
@@ -0,0 +1,105 @@
+*********************
+Type System Variables
+*********************
+
+User written code can be placed in arbitrary places using the
+:doc:`inject-code <codeinjectionsemantics>` tag. To ease the binding developer
+work, the injected code can make use of special variables that will be replaced
+by the correct values. This also shields the developer from some |project|
+implementation specifics.
+
+
+Variables
+=========
+
+**%0**
+
+  Replaced by the name of the return variable of the Python method/function wrapper.
+
+
+**%#**
+
+  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.
+
+
+**%ARGUMENT_NAMES**
+
+  Replaced by a comma separated list with the names of all arguments that were
+  not removed on the type system description for the method/function.
+
+
+**%CONVERTTOPYTHON[CPPTYPE]**
+
+  Replaced by a |project| conversion call that converts a C++ variable of the
+  type indicated by ``CPPTYPE`` to the proper Python object.
+
+
+**%CPPSELF**
+
+  Replaced by the wrapped C++ object instance that owns the method in which the
+  code with this variable was inserted.
+
+
+**%FUNCTION_NAME**
+
+  Replaced by the name of a function or method.
+
+
+**%PYARG_#**
+
+  Similar to ``%#``, but is replaced by the Python arguments (PyObjects)
+  received by the Python wrapper method.
+
+
+**%PYSELF**
+
+  Replaced by the Python wrapper variable (a PyObject) representing the instance
+  bounded to the Python wrapper method which receives the custom code.
+
+
+**%RETURN_TYPE**
+
+  Replaced by the type returned by a function or method.
+
+
+**%TYPE**
+
+  Replaced by the name of the class to which a function belongs. Should be used
+  in code injected to methods.
+
+
+Example
+=======
+
+Just to illustrate the usage of the variables described in the previous
+sections, below is an excerpt from the type system description of a |project|
+test. It changes a method that received ``argc/argv`` arguments into something
+that expects a Python sequence instead.
+
+    .. code-block:: xml
+
+        <modify-function signature="overloadedMethod(int, char**)">
+            <modify-argument index="1">
+                <replace-type modified-type="PySequence" />
+            </modify-argument>
+            <modify-argument index="2">
+                <remove-argument />
+            </modify-argument>
+            <inject-code class="target" position="beginning">
+                int argc;
+                char** argv;
+                if (!PySequence_to_argc_argv(%PYARG_1, &amp;argc, &amp;argv)) {
+                    PyErr_SetString(PyExc_TypeError, "error");
+                    return 0;
+                }
+                %RETURN_TYPE foo = %CPPSELF.%FUNCTION_NAME(argc, argv);
+                %0 = %CONVERTTOPYTHON[%RETURN_TYPE](foo);
+
+                for (int i = 0; i &lt; argc; ++i)
+                    delete[] argv[i];
+                delete[] argv;
+            </inject-code>
+        </modify-function>
+