Python Library Reference is tutorial, not reference

[Josiah Carlson]

> There's nothing like reading good source code to learn to program in
> *any* language. However, there's something that pure source code don't
> tell you, thats the *context* behind its design: the intentions, the
> limitations (which may not be obivous), and the somewhat difficult
> design choices faced by the programmer. For this, good comments are
> important, but nothing beats good reference documentation. In my
> opinion, it should not tell only what each function and argument does:
> it should state how it is supposed to be used, and why does it make
> sense.

Current Python documentation describes the functionality of each
function and method.  Pydoc gives you APIs and the docstring if one is
available.

The only place you are likely to discover rationale is in the source
code itself.  The code for sorting lists has great rationale as for why
Python uses 'Timsort', and not another algorithm.

What it seems like you are suggesting is that the API reference should
get copies of "why we do this here" as listed in the source code. While
it would be interesting, I am not sure it should necessarily be a part
of the documentation (especially API documentation).  People read
documentation because they want to learn how to use something; those
that really want to understand the internals, and why it was designed
and built the way it was, go to the source.


> As for complaining but not writing it myself... well, I really dont
> feel comfortable doing that. English is not my native language, and
> I'm afraid that the material that I write would not be good enough for
> Python's documentation standard. It's one thing to post at c.l.py, and
> another one to submit a documentation patch.

Give it a shot, you may be surprised.

 - Josiah