shiboken: Improve handling of pointer types for CONVERTTOCPP in injected code

Code snippets like:
QByteArray *cppSelf = %CONVERTTOCPP[QByteArray *](obj);

cause an assert in shiboken since the '*' is captured into
the target of the assignment and is not considered part of the type.

Make the error message a bit clearer and add documentation.

Fixes: PYSIDE-1037
Change-Id: Ie8da2f57ba91325ea677e1a00852e91726c0e09b
Reviewed-by: Christian Tismer <tismer@stackless.com>

1 files changed, 23 insertions, 0 deletions

diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystemvariables.rst
index a07ba0d8c..b1b9bbfe6 100644
--- a/sources/shiboken2/doc/typesystemvariables.rst
+++ b/sources/shiboken2/doc/typesystemvariables.rst
@@ -126,6 +126,29 @@ Variables
   Replaced by a |project| conversion call that converts a Python variable
   to a C++ variable of the type indicated by ``CPPTYPE``.
 
+   Typically, this is a variable assignment:
+
+      .. code-block:: c++
+
+         double value = %CONVERTTOCPP[double](pyValue);
+
+   Pointer assignments are also possible:
+
+      .. code-block:: c++
+
+         void f(double *valuePtr)
+         {
+             *valuePtr = %CONVERTTOCPP[double](pyValue);
+
+   Note however, that for variable definitions, the type must
+   be a space-delimited token:
+
+      .. code-block:: c++
+
+         double * valuePtr = %CONVERTTOCPP[double](pyValue);
+
+   since it otherwise would be indistinguishable from the pointer assignment
+   above.
 
 .. _converttopython: