diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 17 |
1 files changed, 12 insertions, 5 deletions
@@ -50,17 +50,24 @@ Human Alphabetical Order Examples 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 - parameters and return types use the Sphinx format. After that an extra - newline then close the quotations. + + """A multiline docstring has a one-line summary, less than 80 characters. + + 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. After + you have finished your descriptions add an extra newline and close the + quotations. When writing the docstring for a class, an extra line should be placed after the closing quotations. For more in-depth explanations for these 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 bar: the bar parameter :returns: description of the return value |