Python Documentation (should be better?)

[Steven Bethard]

Skip Montanaro wrote:
>     Mike> Given that Python hides the difference between user-defined
>     Mike> objects and built-in objects, it's not clear to me that anything
>     Mike> other than the current system, with all the classes/types in one
>     Mike> place, makes sense.
> 
> Maybe the Module Index should be renamed "Module/Type Index" and embellished
> with the builtin types, so that you'd find "float (builtin)", "string
> (builtin)", "dict (builtin)", etc. in the appropriate alphabetical
> positions.

+1

Yeah, I'd love to see something like this.  My preference would actually 
to be to leave the "Global Module Index" the same and add a "Builtin 
Type Index" along the lines of the module index.

One of my current problems with the documentation is that, for builtin 
types, the constructor is found in "Built-in Functions"[1], but the 
methods are found in some subsection of "Built-in Types"[2]. 
Additionally, the "Built-in Types"[2] section mixes protocols like the 
Sequence, Iterator and Mapping protocols with the methods of some of the 
  builtin types that implement these protocols.

Here's what I'd like to see happen:

(1) Restructure the "Built-In Objects"[3] section to split "Built-in 
Types" into "Built-in Protocols" and "Built-in Types".  "Built-in 
Protocols" would describe:

  * the Numeric Procotol (__add__, __sub__, __mul__, etc.)
  * the Iterator Protocol (__iter__, next, etc.)
  * the Sequence Protocol (__len__, __getitem__, __iter__, etc.)
  * the Mapping Protocol  (__len__, __getitem__, __iter__, etc.)
  * the File Protocol (read, write, close, etc.)
  * the Set Protocol (__len__, __contains__, etc.)
and possibly
  * the String Protocol (Sequence Protocol + upper, lower, etc.)

"Built-in Types" would describe the types that implement the above 
Protocols, i.e.:

  * bool (Numeric)
  * complex (Numeric)
  * dict (Mapping)
  * file (File, Iterator)
  * float (Numeric)
  * frozenset (Set)
  * function -- link to description of functions
  * int (Numeric)
  * list (Sequence)
  * long (Numeric)
  * object -- link to description of classes
  * set (Set)
  * str (Sequence)
  * tuple (Sequence)
  * type -- link to description of classes
  * unicode (Sequence)
  * xrange (Sequence)

Not sure if I got them all, but that should be close.  Probably this 
section should also contain all the types listed in "Other Built-in 
Types"[4]

(2) Fill in each new "Built-in Type" section with:

  * the constructor documentation (from "Built-in Functions"[1])
  * links to each Protocol that the type implements
  * descriptions of partial implementations of Protocols (e.g. tuple is 
an immutable Sequence)
  * any additional methods of the type that are not part of a protocol

(3) Add a separate page like "Global Module Index"[4] called "Built-in 
Type Index" that links to the sections of the new "Built-in Types".


IMVHO, this would make finding docs about the builtins much easier.

However, this is a fairly large change.  A simpler change that would 
probably get 60-70% of the benefit, would be to just create the 
"Built-in Type Index" page, and link to the current page describing that 
built-in type's Protocol.  It might be a little confusing to click on a 
link that said "str type" and end up at the "Sequence Types" page, but I 
think people could get over it if the more comprehensive solution isn't 
acceptable.

STeVe

[1] http://docs.python.org/lib/built-in-funcs.html
[2] http://docs.python.org/lib/types.html
[3] http://docs.python.org/lib/builtin.html
[4] http://docs.python.org/lib/typesother.html
[5] http://docs.python.org/modindex.html