search

brata-hsdc / brata

Automatically exported from code.google.com/p/brata
2 stars 0 forks source link

Standardized Docstring Template #86

Open DragonmasterJ opened 8 years ago

DragonmasterJ commented 8 years ago

Decide on a standardized docstring template to use for documenting python code.

jawaad-ahmad commented 8 years ago

From Issue #87:

Proposing the following docstring on at least all public functions (i.e. functions with names that don't begin with an underscore ["_"]).

def function(arg1, arg2):
   """ One-line summary.

   Optional multi-line description if necessary. Good to mention
   any pre-conditions and post-conditions.

   Args:
      arg1 (type): One-line summary
         Optional multi-line
         description if necessary.
      arg2 (type): One-line summary
         Optional multi-line
         description if necessary.

   Returns:
      type: One-line summary.

      Optional multi-line
      description if necessary.

   Raises:
      NameOfError: Conditions in which exception is raised.
   """
   # begin method body
ellerychan commented 8 years ago 
def function(arg1, arg2):
   """ One-line summary.
      ^

May I put a space here?

jawaad-ahmad commented 8 years ago

Probably. I like the space; I would be surprised if any mature docstring extraction tool didn't trim the docstring before processing.

I've always remembered seeing it right against the """ in the examples I've seen.

Let's go ahead and make it as readable as we can till we have reason to change it. I updated the sample above to add the space as you illustrated.