Python Documentation Standards

[Colin J. Williams]

Doc strings provide us with a great opportunity to illuminate our code.

In the example below, __init__ refers us to the class's documentation,
but the class doc doesn't help much.

Are there any guideline which cover such things?

PEP 8 <http://www.python.org/doc/peps/pep-0008/> has general advice.
PEP 257 <http://www.python.org/doc/peps/pep-0257/> provides more
detailed advice.

list provides a trivial example because it is very well documented
elsewhere but it does provide a template for others.

Colin W.

Colin W.
 >>> list.__init__.__doc__
'x.__init__(...) initializes x; see x.__class__.__doc__ for signature'
 >>> list.__new__.__doc__
'T.__new__(S, ...) -> a new object with type S, a subtype of T'
 >>> list.__class__.__doc__
"type(object) -> the object's type\ntype(name, bases, dict) -> a new type"
 >>>