[Python-Dev] Documentation TODO for Python 2.2

[Barry A. Warsaw]

A few days ago, we (Pythonlabs) sat down and tried to figure out what
still needs to be documented for Python 2.2.  We came up with an
impressive list. :)  It's clear that, left up to us, there's no way
we'll be able to get it all done, so we're turning to you to help!

Here's the plan we came up with.  For each of the items in the list
below, we'll add a bug report to SF in the documentation category.
Actually, Fred will do this, and it will auto-assign to him.

If you find a topic that you can volunteer to document, and you are a
SF committer, then simply assign the bug report to yourself and go for
it.  If you are not a SF committer, the bug report will stay assigned
to Fred, and you should coordinate the assignments with him.

Fred's going to oversee this effort, so any questions you might have
(e.g. you're not sure where the documentation for new feature X should
be added), please coordinate with him.

In the list below, some stuff are new language features, some are new
C API functions, etc.  Some things will need to go in the language
ref, some in the library ref.  Some items are already documented to
some degree, and may just need a little work to clean up, or make
consistent with other sections of the manuals.

We've already done a first pass at claiming some of the items in the
list.  Any help you can provide will be very much appreciated.

(Note that the "big one" is documenting new-style classes.  This is a
large bite because classic classes aren't really adequately
documented, and it doesn't make much sense to document new-style
classes independent of classic ones.  Guido is the most qualified to
document new-style classes, but it's doubtful he'll have time, so I
volunteer to do it instead.  Or at least take a crack at it.)

The numbers are rough estimates in days.  Items that are claimed have
that person's initials next to them.

Thanks,
-Barry

PEPs 'n' stuff 4.5
- iterators .5
- generators .5
- nested scopes 1 (JH)
- future division .5
- new builtins .5
- list comprehensions (< .5)
- unifying long & int .5
- extended call syntax (< .5)

Library 2.5
- compiler package 1.5 (JH)
- hotshot 1 (FD)

Classes 6 (GvR or BAW)
- old style classes
- distinction between kinds of classes (new-style and old-style)
- new __ methods
- method resolution order
- metatypes
- coercion
- subclassing builtin types
- slots
- properties / descriptors
- D.B. hook
- attribute lookup rules

C API 4
- new __ slots 1
- subclassing types 1 (JH?)
- METH_O and friends (?)
- writing a new builtin type 2 (JH)

Modules

- pydoc
- smtpd (BAW)
- all the new modules that have been added and not documented

18+ days, and that's being optimistic. :)