470,591 Members | 1,770 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 470,591 developers. It's quick & easy.

Python Documentation Standards

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"

Mar 16 '06 #1
3 1530
Colin J. Williams wrote:
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.


It doesn't?
print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe
Mar 16 '06 #2
Steven Bethard wrote:
Colin J. Williams wrote:
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.


It doesn't?
print list.__doc__ list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe


How about this?:
print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items
See http://docs.python.org/lib/built-in-funcs.html#l2h-44

although it would be better if the online docs had a more permanent looking
anchor.
Mar 16 '06 #3
Steven Bethard wrote:
Colin J. Williams wrote:
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.

It doesn't?
>>> print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe

You are right, I didn't dig far enough.

Colin W.
Mar 17 '06 #4

This discussion thread is closed

Replies have been disabled for this discussion.

By using this site, you agree to our Privacy Policy and Terms of Use.