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.

 

[Steven Bethard]

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?
list() -> new list
list(sequence) -> new list initialized from sequence's items

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

STeVe

 

[Duncan Booth]

It doesn't?

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?:
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.

 

[Colin J. Williams]

It doesn't?

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.