Correct formatting of comments in template, add some more text

diff --git a/templates/template.py b/templates/template.py
index c139b7d..a15d052 100644 (file)
--- a/templates/template.py
+++ b/templates/template.py
@@ -24,20 +24,24 @@ Module name: Summary of this module
 Some overview over important classes and functions and such should be specified
 in this docstring, but please keep it brief!
 
+This is rather long to show you useful spinx commenting options. Also mentions
+some extra formatting rules we adhere to here.
+
+Each code file must have the license specified on top using hash-comments,
+followed by a Copyright note with year and author. No need to specify author
+inside code comments (except maybe for third-party contributions).
+
 
 .. seealso:: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
-.. todo:: Do not forget to correct the codeauthor and license text commented by
-          hashes above.
+.. todo:: Do not forget to update the year in Copyright note above
 .. note:: You should note this
 .. warning:: This is a warning
-
-.. codeauthor:: Intra2net
 """
 
 from __future__ import print_function
 
 THE_CONSTANT = None
-""" some constant with docstring *AFTER* the constant. Use this format! """
+"""Some constant with docstring *AFTER* the constant."""
 
 
 ANOTHER_CONSTANT = 1     #: short docstring in same line -- note the #:
@@ -48,22 +52,32 @@ THIRD_CONST = 3.333
 
 class TestClass:
     """
-    test class
+    Test class.
+
+    Note how this comment consists of (almost) proper sentences, beginning with
+    an uppercase letter and ending with a period.
+
+    Note also, that the starting and ending triple quotation marks get their
+    own lines and that there is no blank line after the comment is closed. That
+    is as it should be.
 
-    does nothing, really
+    Other than that, this class does nothing, really.
     """
 
     def __init__(self, args):
-        """ constructor, gets its own paragraph in documentation
+        """
+        Constructor, gets its own paragraph in documentation.
 
         :raises NotImplementedError: always
         """
         raise NotImplementedError()
 
     def test_method(self, arg):
-        """ test method, does nothing
+        """
+        Test method, does nothing.
 
-        for more doc string examples, see function :py:func:`send_message`
+        For more doc string examples, see function :py:func:`send_message`.
+        However, we might have more stringent formatting requirements here.
 
         :param arg: some argument
         :return: Nothing
@@ -74,7 +88,8 @@ class TestClass:
 
 
 def send_message(sender, recipient, message_body, priority=1):
-    """ Send a message to a recipient
+    """
+    Send a message to a recipient
 
     Example for a docstring that uses lots of reST fields, taken from
     http://sphinx-doc.org/domains.html
@@ -98,5 +113,4 @@ def send_message(sender, recipient, message_body, priority=1):
     :raises TypeError: if the message_body is not a basestring
     :raises NotImplementedError: always
     """
-
     raise NotImplementedError()