Use Python-ish, not C++, parameter types in Python documentation.

Using C++ types in documentation for Python users is more harmful than
useless, so use Python types whenever possible and allow defining "doctype"
typemap to customize this for the user-defined types.

Doc/Manual/Doxygen.html

@@ -943,6 +943,43 @@ class Shape(_object):
         return _Shapes.Shape_perimeter(self)
 </pre></div>
 
+<p>
+If any parameters of a function or a method are documented in the Doxygen comment,
+their description is copied into the generated output using
+<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example
+</p>
+<div class="code"><pre>
+/**
+    Set a breakpoint at the given location.
+
+    @param filename The full path to the file.
+    @param line_number The line number in the file.
+ */
+bool SetBreakpoint(const char* filename, int line_number);
+</pre></div>
+would be translated to
+<div class="targetlang"><pre>
+def SetBreakpoint(*args):
+    r"""
+    Set a breakpoint at the given location.
+
+    :type filename: string
+    :param filename: The full path to the file.
+    :type line_number: int
+    :param line_number: The line number in the file.
+    """
+</pre></div>
+<p>
+The types used for the parameter documentation come from <tt>doctype</tt> typemap which
+is defined for all the primitive types and a few others (e.g. <tt>std::string</tt> and
+<tt>shared_ptr&lt;T&gt;</tt>) but for non-primitive types is taken to be just the C++
+name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a dot. To
+change this, you can define your own typemaps for the custom types, e.g:
+</p>
+<div class="code"><pre>
+%typemap(doctype) MyDate "datetime.date";
+</pre></div>
+
 <p>
 Currently Doxygen comments assigned to vars are not present in proxy
 file, so they have no comment translated for them.

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -73,7 +73,7 @@ commentVerifier.check(doxygen_basic_translate.function7.__doc__,
     """
     Test for a parameter with difficult type
     (mostly for python)
-    :type a: Shape::superType *[10]
+    :type a: Shape
     :param a: Very strange param
     """
 )

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -10,11 +10,11 @@ commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__,
     r"""
     Returns address of file line.
 
-    :type fileName: int &
+    :type fileName: int
     :param fileName: name of the file, where the source line is located
     :type line: int
     :param line: line number
-    :type isGetSize: bool
+    :type isGetSize: boolean
     :param isGetSize: if set, for every object location both address and size are returned
 
     Connection::getId() 
@@ -141,7 +141,7 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__,
             main_ctrl.setBP("func1");
         
 
-    :type fileName: char *
+    :type fileName: string
     :param fileName: name of the log file
     """
 );

Lib/python/boost_shared_ptr.i

@@ -314,6 +314,9 @@
 #error "typemaps for $1_type not available"
 %}
 
+%typemap(doctype) SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE >,
+                  SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE >& %{TYPE%}
+
 
 %template() SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE >;
 

Lib/python/pydocs.swg

@@ -22,3 +22,24 @@
 %typemap(doc) SWIGTYPE *INPUT, SWIGTYPE &INPUT "$1_name: $1_type (input)";
 %typemap(doc) SWIGTYPE *OUTPUT, SWIGTYPE &OUTPUT "$1_name: $1_type (output)";
 #endif
+
+
+// Types to use in Python documentation for the parameters of the given C++ type.
+%typemap(doctype) bool "boolean";
+
+%define int_doctype_for_cppint_type(cppint_type)
+    %typemap(doctype) cppint_type, unsigned cppint_type "int";
+%enddef
+%formacro(int_doctype_for_cppint_type, short, int, long, long long)
+
+%typemap(doctype) size_t "int";
+
+%typemap(doctype) enum SWIGTYPE "int";
+
+%typemap(doctype) float, double, long double "float";
+
+%typemap(doctype) char*, std::string "string";
+
+%typemap(doctype) SWIGTYPE "$1_basetype"
+%typemap(doctype) SWIGTYPE * "$typemap(doctype, $*1_ltype)"
+%typemap(doctype) SWIGTYPE & "$typemap(doctype, $*1_ltype)"

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -246,8 +246,16 @@ std::string PyDocConverter::getParamType(std::string param)
     if (Char (Getattr(p, "name")) != param)
       continue;
 
-    String *s = SwigType_str(Getattr(p, "type"), "");
+    String *s = Swig_typemap_lookup("doctype", p, Getattr(p, "name"), 0);
+    if (!s)
+      s = SwigType_str(Getattr(p, "type"), "");
+
+    // In Python C++ namespaces are flattened, so remove all but last component
+    // of the name.
+    String * const last = Swig_scopename_last(s);
+
     type = Char (s);
+    Delete(last);
     Delete(s);
     break;
   }