[PYTHON DOC-SIG] doc string style question

Robin Friedrich friedric@rose.rsoc.rockwell.com
Thu, 22 Aug 1996 13:00:32 -0500

|> From: mclay@eeel.nist.gov (Michael McLay)
|> My docstring style keeps dithering since I haven't found a well
|> defined convention to follow.  Is there a WWW page on this that I've
|> missed?   

No. but there should be when we can all converge on a tool.

|> What's the recommended style for writting doc strings inside
|> classes and function. 

I use the following style.

def mif_escape(text):
    """Substitute the appropriate tokens for problematic characters.
    As you can see the python-mode will wrap the
    verbose author's text to tab level 1 when the return is struck.
    split = string.split
    join  = string.join

gendoc currently figures out the initial indent for the doc string
and strips it off the text body.
Also remember the "one liner" rule. The doc string should have the 
first line a summary of the purpose and the rest of the doc string 
is after a blank line.

DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org