[FRPythoneers] Documenting inside Python

Evelyn Mitchell efm at tummy.com
Tue May 1 10:57:18 MDT 2001


On Tue, May 01, 2001 at 10:50:36AM -0600, J. Wayde Allen wrote:
> 
> While we're at it, I'm assuming that a "good" Python programmer would
> include the __doc__ feature into his or her code?  Is there a
> "standard" way to do this or does one just define
> 
>        self.__doc__ = "Some string of instructions"

Yes, the convention is this:

Use triple quoted strings (multi-line strings) ''' '''
The first line is a brief description.  More detail on usage follows
the first line.

Sean uses this format for doc strings:

'''One line description

RETURNS: description of the return code
EXCEPTIONS: what exceptions does this throw
ARGUMENTS:
	- argument -- description of argument
'''

Pretty much every python program that manipulates __doc__ strings
uses the one-liner. The RETURNS, EXCEPTIONS and ARGUMENTS headers
make for readable comments. 

And, I'd be remiss if I didn't mention pydoc (http://www.pydoc.org).

Evelyn Mitchell
efm at tummy.com



More information about the FRPythoneers mailing list