Merge pull request #3468 from RelentlessIdiot/numpydoc_returns_unnamed

ENH: Allow unnamed return values in Returns section of doc string

5 files changed, 82 insertions, 26 deletions

diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt
index eeedd3204..13e9b2607 100644
--- a/doc/HOWTO_DOCUMENT.rst.txt
+++ b/doc/HOWTO_DOCUMENT.rst.txt
@@ -225,14 +225,30 @@ The sections of the docstring are:
 
 5. **Returns**
 
-   Explanation of the returned values and their types, of the same
-   format as **parameters**.
+   Explanation of the returned values and their types. Similar to the
+   **parameters** section, except the name of each return value is optional.
+   The type of each return value is always required::
+
+     Returns
+     -------
+     int
+         Description of anonymous integer return value.
+
+   If both the name and type are specified, the **returns** section takes the
+   same form as the **parameters** section::
+
+     Returns
+     -------
+     err_code : int
+         Non-zero value indicates error code, or zero on success.
+     err_msg : str or None
+         Human readable error message, or None on success.
 
 6. **Other parameters**
 
    An optional section used to describe infrequently used parameters.
    It should only be used if a function has a large number of keyword
-   prameters, to prevent cluttering the **parameters** section.
+   parameters, to prevent cluttering the **parameters** section.
 
 7. **Raises**
 
diff --git a/doc/example.py b/doc/example.py
index 71c1a2f30..03be59d18 100644
--- a/doc/example.py
+++ b/doc/example.py
@@ -57,14 +57,12 @@ def foo(var1, var2, long_var_name='hi') :
 
     Returns
     -------
+    type
+        Explanation of anonymous return value of type ``type``.
     describe : type
-        Explanation
-    output : type
-        Explanation
-    tuple : type
-        Explanation
-    items : type
-        even more explaining
+        Explanation of return value named `describe`.
+    out : type
+        Explanation of `out`.
 
     Other Parameters
     ----------------
diff --git a/doc/sphinxext/numpydoc/docscrape.py b/doc/sphinxext/numpydoc/docscrape.py
index a36171855..4ee0f2e40 100644
--- a/doc/sphinxext/numpydoc/docscrape.py
+++ b/doc/sphinxext/numpydoc/docscrape.py
@@ -334,7 +334,10 @@ class NumpyDocString(object):
         if self[name]:
             out += self._str_header(name)
             for param,param_type,desc in self[name]:
-                out += ['%s : %s' % (param, param_type)]
+                if param_type:
+                    out += ['%s : %s' % (param, param_type)]
+                else:
+                    out += [param]
                 out += self._str_indent(desc)
             out += ['']
         return out
diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py
index 03c37a4a7..1ebce8ccb 100644
--- a/doc/sphinxext/numpydoc/docscrape_sphinx.py
+++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py
@@ -42,16 +42,37 @@ class SphinxDocString(NumpyDocString):
     def _str_extended_summary(self):
         return self['Extended Summary'] + ['']
 
+    def _str_returns(self):
+        out = []
+        if self['Returns']:
+            out += self._str_field_list('Returns')
+            out += ['']
+            for param, param_type, desc in self['Returns']:
+                if param_type:
+                    out += self._str_indent(['**%s** : %s' % (param.strip(),
+                                                              param_type)])
+                else:
+                    out += self._str_indent([param.strip()])
+                if desc:
+                    out += ['']
+                    out += self._str_indent(desc, 8)
+                out += ['']
+        return out
+
     def _str_param_list(self, name):
         out = []
         if self[name]:
             out += self._str_field_list(name)
             out += ['']
-            for param,param_type,desc in self[name]:
-                out += self._str_indent(['**%s** : %s' % (param.strip(),
-                                                          param_type)])
-                out += ['']
-                out += self._str_indent(desc,8)
+            for param, param_type, desc in self[name]:
+                if param_type:
+                    out += self._str_indent(['**%s** : %s' % (param.strip(),
+                                                              param_type)])
+                else:
+                    out += self._str_indent(['**%s**' % param.strip()])
+                if desc:
+                    out += ['']
+                    out += self._str_indent(desc, 8)
                 out += ['']
         return out
 
@@ -196,8 +217,9 @@ class SphinxDocString(NumpyDocString):
         out += self._str_index() + ['']
         out += self._str_summary()
         out += self._str_extended_summary()
-        for param_list in ('Parameters', 'Returns', 'Other Parameters',
-                           'Raises', 'Warns'):
+        out += self._str_param_list('Parameters')
+        out += self._str_returns()
+        for param_list in ('Other Parameters', 'Raises', 'Warns'):
             out += self._str_param_list(param_list)
         out += self._str_warnings()
         out += self._str_see_also(func_role)
diff --git a/doc/sphinxext/numpydoc/tests/test_docscrape.py b/doc/sphinxext/numpydoc/tests/test_docscrape.py
index 7b7375a5a..b682504e1 100644
--- a/doc/sphinxext/numpydoc/tests/test_docscrape.py
+++ b/doc/sphinxext/numpydoc/tests/test_docscrape.py
@@ -47,6 +47,9 @@ doc_txt = '''\
 
       In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
       value drawn from the distribution.
+  list of str
+      This is not a real return value.  It exists to test
+      anonymous return values.
 
   Other Parameters
   ----------------
@@ -148,13 +151,19 @@ def test_other_parameters():
     assert desc[0].startswith('A parrot off its mortal coil')
 
 def test_returns():
-    assert_equal(len(doc['Returns']), 1)
+    assert_equal(len(doc['Returns']), 2)
     arg, arg_type, desc = doc['Returns'][0]
     assert_equal(arg, 'out')
     assert_equal(arg_type, 'ndarray')
     assert desc[0].startswith('The drawn samples')
     assert desc[-1].endswith('distribution.')
 
+    arg, arg_type, desc = doc['Returns'][1]
+    assert_equal(arg, 'list of str')
+    assert_equal(arg_type, '')
+    assert desc[0].startswith('This is not a real')
+    assert desc[-1].endswith('anonymous return values.')
+
 def test_notes():
     assert doc['Notes'][0].startswith('Instead')
     assert doc['Notes'][-1].endswith('definite.')
@@ -218,6 +227,9 @@ out : ndarray
 
     In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
     value drawn from the distribution.
+list of str
+    This is not a real return value.  It exists to test
+    anonymous return values.
 
 Other Parameters
 ----------------
@@ -226,12 +238,12 @@ spam : parrot
 
 Raises
 ------
-RuntimeError :
+RuntimeError
     Some error
 
 Warns
 -----
-RuntimeWarning :
+RuntimeWarning
     Some warning
 
 Warnings
@@ -334,6 +346,11 @@ of the one-dimensional normal distribution to higher dimensions.
         In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
         value drawn from the distribution.
 
+    list of str
+
+        This is not a real return value.  It exists to test
+        anonymous return values.
+
 :Other Parameters:
 
     **spam** : parrot
@@ -342,13 +359,13 @@ of the one-dimensional normal distribution to higher dimensions.
 
 :Raises:
 
-    **RuntimeError** :
+    **RuntimeError**
 
         Some error
 
 :Warns:
 
-    **RuntimeWarning** :
+    **RuntimeWarning**
 
         Some warning
 
@@ -698,11 +715,11 @@ def test_class_members_doc():
 
     Methods
     -------
-    a :
+    a
 
-    b :
+    b
 
-    c :
+    c
 
     .. index::