numpy/numpy — pull request #3468 by RelentlessIdiot (2013-06-25 06:11:22+00:00)
Title: ENH: Allow unnamed return values in Returns section of doc string

The current numpy documentation spec says that the `Returns` section uses the
same format as the `Parameters` section, which requires a name for each
parameter. Named return values are not a part of the python language, yet the
`Returns` section requires a name for each return value. Requiring developers
to document names for return values – especially when a function returns only
one value – opens the door to arbitrary and potentially misleading names.

## Proposed Enhancement

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.