Docstrings (was: Re: private)

[Hans Nowak]

James Kew wrote:

>>I would think docstrings, comments, and naming conventions sufficient
>>to provide a method for documenting what a class ought to be accessing.
> 
> I think that's a journey I'm only just beginning.
> 
> Is there any good newbie documentation for docstrings? After reading the
> Tutorial, Library Reference, and most of Dive Into Python as shipped with
> the ActiveState distribution they're still very much a mystery to me...

Not sure there's much to document; the tutorial pretty much says it all.

People use docstrings to document functions, classes and modules. This 
information can later be retrieved with the __doc__ attribute, for example:

 >>> def foo(x):
	""" Do something. """
	return dosomething(x)

 >>> foo.__doc__
' Do something. '

It is also used by the help() function:

 >>> help(foo)
Help on function foo in module __main__:

foo(x)
      Do something.

The above is one of the reasons to use a docstring rather than a comment (which 
would serve the same purpose when eyeballing code). Another reason is that 
there are various tools out there that extract docstrings, and use them for 
e.g. generating documentation automatically, etc.

HTH,

-- 
Hans (base64.decodestring('d3VybXlAZWFydGhsaW5rLm5ldA=='))
# decode for email address ;-)
The Pythonic Quarter:: http://www.awaretek.com/nowak/