From 6aa9cd37a5aae7134cd65e72c9c98551ae15ec5a Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vz-swig@zeitlins.org>
Date: Mon, 11 Aug 2014 16:22:48 +0200
Subject: [PATCH] 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.
---
 .../python/doxygen_basic_translate_runme.py   |  2 +
 .../doxygen_translate_all_tags_runme.py       |  3 +
 .../python/doxygen_translate_runme.py         |  3 +
 .../DoxygenTranslator/src/PyDocConverter.cpp  | 63 ++++++++++++-------
 4 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index 4f8505e24..87010ee39 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/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``.
     """
 )
diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
index 9df2df593..d0bd43980 100644
--- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py
+++ b/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
 
     """)
diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py
index 788bc90eb..92850aa19 100644
--- a/Examples/test-suite/python/doxygen_translate_runme.py
+++ b/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
diff --git a/Source/DoxygenTranslator/src/PyDocConverter.cpp b/Source/DoxygenTranslator/src/PyDocConverter.cpp
index 065c8f4da..9203904c5 100644
--- a/Source/DoxygenTranslator/src/PyDocConverter.cpp
+++ b/Source/DoxygenTranslator/src/PyDocConverter.cpp
@@ -334,6 +334,38 @@ PyDocConverter::PyDocConverter(int flags) :
   fillStaticTables();
 }
 
+// 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;
+
+  String *s = Swig_typemap_lookup("doctype", n, lname, 0);
+  if (!s)
+    s = SwigType_str(Getattr(n, "type"), "");
+
+  if (Language::classLookup(s)) {
+    // In Python C++ namespaces are flattened, so remove all but last component
+    // of the name.
+    String * const last = Swig_scopename_last(s);
+
+    // We are not actually sure whether it's a documented class or not, but
+    // there doesn't seem to be any harm in making it a reference if it isn't,
+    // while there is a lot of benefit in having a hyperlink if it is.
+    type = ":py:class:`";
+    type += Char (last);
+    type += "`";
+
+    Delete(last);
+  } else {
+    type = Char(s);
+  }
+
+  Delete(s);
+
+  return type;
+}
+
 std::string PyDocConverter::getParamType(std::string param)
 {
   std::string type;
@@ -344,28 +376,7 @@ std::string PyDocConverter::getParamType(std::string param)
     if (Char (pname) != param)
       continue;
 
-    String *s = Swig_typemap_lookup("doctype", p, pname, 0);
-    if (!s)
-      s = SwigType_str(Getattr(p, "type"), "");
-
-    if (Language::classLookup(s)) {
-      // In Python C++ namespaces are flattened, so remove all but last component
-      // of the name.
-      String * const last = Swig_scopename_last(s);
-
-      // We are not actually sure whether it's a documented class or not, but
-      // there doesn't seem to be any harm in making it a reference if it isn't,
-      // while there is a lot of benefit in having a hyperlink if it is.
-      type = ":py:class:`";
-      type += Char (last);
-      type += "`";
-
-      Delete(last);
-    } else {
-      type = Char(s);
-    }
-
-    Delete(s);
+    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);
 }