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

Developers usually only need the type of a return value
followed by a brief description. However, in some cases
providing a name for a return value can make the documentation
clearer. This enhancement changes the format of the Returns
section such that the type is required, and the name is
optional:

    Returns
    -------
    int
        Description of anonymous integer return value.
    x : str
        Description of string return value named `x`.

With this change, if a colon is not present, then the entire
line is interpreted as the return type. In all other cases,
the Returns section is interpreted according to the current
rules.

Consistent with the current format, if a colon is present, then
the text to the left of the colon is interpreted as the name;
and the text to the right of the colon is interpreted as the
type. This makes the proposed change backwards compatible with
existing documentation.

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::