Python Library Reference is tutorial, not reference

[Carlos Ribeiro]

On Sat, 16 Oct 2004 14:38:17 -0700, Josiah Carlson <jcarlson at uci.edu> wrote:
> With that said, I find reading the source to be very 
> educational as to how other people do things, but 
> prefer to read /real/ source rather than merely the 
> interfaces to a particular module or class.  

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.

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.


-- 
Carlos Ribeiro
Consultoria em Projetos
blog: http://rascunhosrotos.blogspot.com
blog: http://pythonnotes.blogspot.com
mail: carribeiro at gmail.com
mail: carribeiro at yahoo.com