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 -- http://mail.python.org/mailman/listinfo/python-list
