openstack-attic/melange
Code Issues Proposed changes

HACKING update for docstrings

Browse Source
This commit is contained in:
termie 2011-03-28 10:46:02 -07:00
parent dac54178e2
commit 6b60e85716
1 changed files with 10 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
HACKING
View File

@ -50,17 +50,22 @@ Human Alphabetical Order Examples
Docstrings Docstrings
---------- ----------
"""Summary of the function, class or method, less than 80 characters. """A one line docstring looks like this and ends in a period."""
New paragraph after newline that explains in more detail any general
information about the function, class or method. After this, if defining """A multiline docstring has a one-line summary, less than 80 characters.
parameters and return types use the Sphinx format. After that an extra
newline then close the quotations. Then a new paragraph after a newline that explains in more detail any
general information about the function, class or method. Example usages
are also great to have here if it is a complex class for function.
When writing the docstring for a class, an extra line should be placed When writing the docstring for a class, an extra line should be placed
after the closing quotations. For more in-depth explanations for these after the closing quotations. For more in-depth explanations for these
decisions see http://www.python.org/dev/peps/pep-0257/ decisions see http://www.python.org/dev/peps/pep-0257/
If you are going to describe parameters and return values, use Sphinx, the
appropriate syntax is as follows.
:param foo: the foo parameter :param foo: the foo parameter
:param bar: the bar parameter :param bar: the bar parameter
:returns: description of the return value :returns: description of the return value