attempts to make the docstring rules clearer

1 files changed, 12 insertions, 5 deletions

diff --git a/HACKING b/HACKING
index e58d60e58..2f364c894 100644
--- a/HACKING
+++ b/HACKING
@@ -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