Document the return type when translating Doxygen @return to Python.

In addition to translating the comment itself, also document the type of the
object returned. This is consistent with generating not only :param: but also
:type: for the parameters documented using @param.

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -13,6 +13,7 @@ commentVerifier.check(doxygen_basic_translate.function.__doc__,
 
     Author: Some author
 
+    :rtype: int
     :return: Some number
 
     See also: function2
@@ -86,6 +87,7 @@ commentVerifier.check(doxygen_basic_translate.Atan2.__doc__,
     :param y: Vertical coordinate.
     :type x: float
     :param x: Horizontal coordinate.
+    :rtype: float
     :return: Arc tangent of ``y/x``.
     """
 )

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -263,10 +263,13 @@ r"""
 
     Another remarks section
 
+    :rtype: int
     :return: Whatever
 
+    :rtype: int
     :return: it
 
+    :rtype: int
     :return: may return
 
     """)

Examples/test-suite/python/doxygen_translate_runme.py

@@ -99,10 +99,13 @@ r"""
 
     Another remarks section
 
+    :rtype: int
     :return: Whatever
 
+    :rtype: int
     :return: it
 
+    :rtype: int
     :return: may return
 
     See also: someOtherMethod

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -334,19 +334,15 @@ PyDocConverter::PyDocConverter(int flags) :
   fillStaticTables();
 }
 
-std::string PyDocConverter::getParamType(std::string param)
+// Return the type as it should appear in the output documentation.
+static
+std::string getPyDocType(Node* n, const_String_or_char_ptr lname = "")
 {
   std::string type;
 
-  ParmList *plist = CopyParmList(Getattr(currentNode, "parms"));
+  String *s = Swig_typemap_lookup("doctype", n, lname, 0);
-  for (Parm *p = plist; p;p = nextSibling(p)) {
-    String* pname = Getattr(p, "name");
-    if (Char (pname) != param)
-      continue;
-
-    String *s = Swig_typemap_lookup("doctype", p, pname, 0);
   if (!s)
-      s = SwigType_str(Getattr(p, "type"), "");
+    s = SwigType_str(Getattr(n, "type"), "");
 
   if (Language::classLookup(s)) {
     // In Python C++ namespaces are flattened, so remove all but last component
@@ -366,6 +362,21 @@ std::string PyDocConverter::getParamType(std::string param)
   }
 
   Delete(s);
+
+  return type;
+}
+
+std::string PyDocConverter::getParamType(std::string param)
+{
+  std::string type;
+
+  ParmList *plist = CopyParmList(Getattr(currentNode, "parms"));
+  for (Parm *p = plist; p;p = nextSibling(p)) {
+    String* pname = Getattr(p, "name");
+    if (Char (pname) != param)
+      continue;
+
+    type = getPyDocType(p, pname);
     break;
   }
   Delete(plist);
@@ -619,6 +630,14 @@ void PyDocConverter::handleTagReturn(DoxygenEntity &tag,
 {
   IndentGuard indent(translatedComment, m_indent);
 
+  const std::string pytype = getPyDocType(currentNode);
+  if (!pytype.empty()) {
+    translatedComment += ":rtype: ";
+    translatedComment += pytype;
+    translatedComment += "\n";
+    translatedComment += indent.getFirstLineIndent();
+  }
+
   translatedComment += ":return: ";
   handleParagraph(tag, translatedComment);
 }