From dd4c680a02b53c813d5d6d7270f0a758449f07fc Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 13 Jul 2014 00:46:31 +0200 Subject: [PATCH] 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 | 37 +++++++++++++++++++ .../python/doxygen_basic_translate_runme.py | 2 +- .../python/doxygen_misc_constructs_runme.py | 6 +-- Lib/python/boost_shared_ptr.i | 3 ++ Lib/python/pydocs.swg | 21 +++++++++++ .../DoxygenTranslator/src/PyDocConverter.cpp | 10 ++++- 6 files changed, 74 insertions(+), 5 deletions(-) diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html index 9e0b3d813..d927593ab 100644 --- a/Doc/Manual/Doxygen.html +++ b/Doc/Manual/Doxygen.html @@ -943,6 +943,43 @@ class Shape(_object): return _Shapes.Shape_perimeter(self) +

+If any parameters of a function or a method are documented in the Doxygen comment, +their description is copied into the generated output using +Sphinx documentation conventions. For example +

+
+/**
+    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);
+
+would be translated to +
+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.
+    """
+
+

+The types used for the parameter documentation come from doctype typemap which +is defined for all the primitive types and a few others (e.g. std::string and +shared_ptr<T>) but for non-primitive types is taken to be just the C++ +name of the type with namespace scope delimiters (::) replaced with a dot. To +change this, you can define your own typemaps for the custom types, e.g: +

+
+%typemap(doctype) MyDate "datetime.date";
+
+

Currently Doxygen comments assigned to vars are not present in proxy file, so they have no comment translated for them. diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py index a0c921829..303b81a45 100644 --- a/Examples/test-suite/python/doxygen_basic_translate_runme.py +++ b/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 """ ) diff --git a/Examples/test-suite/python/doxygen_misc_constructs_runme.py b/Examples/test-suite/python/doxygen_misc_constructs_runme.py index 2c68fd65d..183fc870f 100644 --- a/Examples/test-suite/python/doxygen_misc_constructs_runme.py +++ b/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 """ ); diff --git a/Lib/python/boost_shared_ptr.i b/Lib/python/boost_shared_ptr.i index 100ed3e82..560a49f81 100644 --- a/Lib/python/boost_shared_ptr.i +++ b/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 >; diff --git a/Lib/python/pydocs.swg b/Lib/python/pydocs.swg index 969af92aa..1eea41b8d 100644 --- a/Lib/python/pydocs.swg +++ b/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)" diff --git a/Source/DoxygenTranslator/src/PyDocConverter.cpp b/Source/DoxygenTranslator/src/PyDocConverter.cpp index 607e339b6..05df48c0f 100644 --- a/Source/DoxygenTranslator/src/PyDocConverter.cpp +++ b/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; }