From 7d9ffbed3327af8cda41e2b04e2676c0a69f6a30 Mon Sep 17 00:00:00 2001 From: termie Date: Mon, 28 Mar 2011 10:46:02 -0700 Subject: [PATCH 1/2] HACKING update for docstrings --- HACKING | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/HACKING b/HACKING index e58d60e5..95afc0f7 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 From 99d31ab25b07890ef287c0fdfc31a540d48d523b Mon Sep 17 00:00:00 2001 From: termie Date: Tue, 29 Mar 2011 11:15:16 -0700 Subject: [PATCH 2/2] accidentally dropped a sentence --- HACKING | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/HACKING b/HACKING index 95afc0f7..2f364c89 100644 --- a/HACKING +++ b/HACKING @@ -57,7 +57,9 @@ Docstrings 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. + 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