Python Documentation Standards

[Duncan Booth]

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.