[Python-Dev] Python core documentation

[Rodrigo Bernardo Pimentel]

        Hi!

        I sent this to Fred Drake a few weeks ago but got no response. I
assume he's busy, or maybe my message never reached him. I hope some of you
will have opinions on this (BTW, please Cc: me on any replies, as I am not
on python-dev).

        (Original message below)

        I was sharing some ideas with Gustavo Niemeyer (who's also receiving
a copy of this message) and he told me you'd be the right person to talk
to [he was also the one who recommended that I resent it to python-dev].

        I'm relatively new to Python, my first project with it started at
the beginning of 2004. And, from the start, its documentation bugged me a
little. Now I'm completely hooked and am a full-time Python programmer, but
I still see the same quirks in documentation.

        I don't mean to say there's lack of it, but I think it needs some
work, it seems quite incomplete. I see some of these characteristics in the
tutorial and module documentation, but I'm refering mostly to internal
documentation.

        A simple example:

>>> [].sort.__doc__
L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1

        While it may seem obvious to somewhat experiencied programmers, it
should be explicit, at least for newbies, what "-1, 0, 1" means, in term of
comparison (and also what happens if cmpfunc is left out - since it defaults
to None, one could think no sorting takes place). But this is relatively
minor, and not the best example.

>>> [].remove.__doc__
L.remove(value) -- remove first occurrence of value

        What if L doesn't contain 'value', does it raise an exception or
does it fail quietly? Does 'remove return anything (the new list, maybe)?

>>> [].pop.__doc__
L.pop([index]) -> item -- remove and return item at index (default last)

        What if L is empty?

        I think you see what I'm getting at: there's a lack of
standardization and completeness that can be frustrating, especially for
those new to Python and to programming. When I came to Python, I was already
a long-time C and Perl programmer, and I got around these things quite
easily, mainly by testing at the prompt or sometimes reading source code,
but, still, it doesn't seem like a very pythonic way of doing things
(explicit better than implicit?). Not to mention clever editors, which could
benefit from standard, complete documentation. There are even some modules
with empty docstrings, which I think should be strictly forbidden in core
modules. For instance:

>>> thread.error.__doc__
>>>

        As I told Niemeyer, I considered sending documentation patches, but
I think a standard should be defined first, and then volunteers (myself
included) could sweep over the core language and conform documentation to
it. I'm willing to work on it and help however I can, but I wanted to
discuss it first (that's why I came to Niemeyer).

        Well, let me know what you think.

        Cheers,



                rbp
-- 
 Rodrigo Bernardo Pimentel <rbp at isnomore.net> | GPG KeyId: <0x0DB14978>
 http://isnomore.net

I'll rule you all with an iron fist! [...]
You! Obey the fist!
          -- Invader Zim