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.[color=blue][color=green][color=darkred]
>>> list.__init__._ _doc__[/color][/color][/color]
'x.__init__(... ) initializes x; see x.__class__.__d oc__ for signature'[color=blue][color=green][color=darkred]
>>> list.__new__.__ doc__[/color][/color][/color]
'T.__new__(S, ...) -> a new object with type S, a subtype of T'[color=blue][color=green][color=darkred]
>>> list.__class__. __doc__[/color][/color][/color]
"type(objec t) -> the object's type\ntype(name , bases, dict) -> a new type"[color=blue][color=green][color=darkred]
>>>[/color][/color][/color]

[Steven Bethard]

Re: Python Documentation Standards

Colin J. Williams wrote:[color=blue]
> 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.[/color]

It doesn't?
[color=blue][color=green][color=darkred]
>>> print list.__doc__[/color][/color][/color]
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]

Re: Python Documentation Standards

Steven Bethard wrote:
[color=blue]
> Colin J. Williams wrote:[color=green]
>> 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.[/color]
>
> It doesn't?
>[color=green][color=darkred]
> >>> print list.__doc__[/color][/color]
> list() -> new list
> list(sequence) -> new list initialized from sequence's items
>
> What is it you were hoping to see in constructor documentation?
>
> STeVe[/color]

How about this?:
[color=blue][color=green][color=darkred]
>>> print list.__doc__[/color][/color][/color]
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]

Re: Python Documentation Standards

Steven Bethard wrote:[color=blue]
> Colin J. Williams wrote:
>[color=green]
>> 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.[/color]
>
>
> It doesn't?
>[color=green][color=darkred]
> >>> print list.__doc__[/color][/color]
> list() -> new list
> list(sequence) -> new list initialized from sequence's items
>
> What is it you were hoping to see in constructor documentation?
>
> STeVe[/color]
You are right, I didn't dig far enough.

Colin W.