From c84fedd4724463e3ce9755c4573658be902d4cd3 Mon Sep 17 00:00:00 2001 From: termie Date: Mon, 28 Mar 2011 10:46:02 -0700 Subject: [PATCH] HACKING update for docstrings --- HACKING | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/HACKING b/HACKING index e58d60e58..95afc0f74 100644 --- a/HACKING +++ b/HACKING @@ -50,17 +50,22 @@ 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. 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