robruana/numpy

Numpy main repository

numpy's Issues

Enhancement to "Returns" section for numpy doc strings

Abstract

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 proposal would change 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 the proposed 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.

Examples

A simple string method from the stdlib that returns a boolean:

.. method:: str.isalpha()

   Determines if all characters in the string are alphabetic.

   For 8-bit strings, this method is locale-dependent.

   Returns
   -------
   bool
      True if all characters in the string are alphabetic 
      and there is at least one character, False otherwise.

A string method from the std lib that returns three values:

.. method:: str.partition(sep)

   Split the string at the first occurrence of `sep`.

   Parameters
   ----------
   sep : str
       Substring of one or more characters to find in the string.

   Returns
   -------
   before_sep : str
      The part of the string before `sep`, or the entire string if `sep` is not found.
   found_sep : str
      The separator itself, or an empty string if `sep` is not found.
   after_sep : str
      The part of the string after `sep`, or an empty string if `sep` is not found.