Formatting Docstrings

To specify that a function returns multiple values do the following within the docstring:

Example docstring for a function that returns multiple values.

Normal reStructuredText blocks can be used within docstrings:

Example docstring for a function with fancy whitespace formatting within the main docstring block.

Multi-line descriptions must be formatted differently depending on where they lie in the docstring. In the main block, each subsequent line should remain flush with the first line:

Example of a multi-line description within the main text block of a docstring.

In the arguments, each subsequent line should be indented a few spaces (or a tab) from the first line:

Example of a multi-line description for a function argument.

In the returns, each subsequent line should remain flush with the text of the first line (not the hyphen in the case of multiple return values):

Example of a multi-line description for a single return value. Example of a multi-line description for multiple return values.