James T. Dennis
jadestar at idiom.com
Fri Jul 18 22:50:10 CEST 2003
Sean 'Shaleh' Perry <shalehperry at comcast.net> wrote:
>> If my english was better I would love to help improve the python
>> documentation, most modules in the standard libraries lack good
>> examples how to *use* them with just a simple description. And a
>> short motivation for the design of a module if possible like "just
>> copied the C API" or "Because of efficiency ..." or "We use a class
>> framework here because ...". A gigantic task. The PSL book by effbot
>> is great but it's a book. And it needs a new version.
> part of the reason why the docs are not but so great is that most of the
> library is Python code which means any questions can be answered by reading
> the source. I find myself doing this quite often.
As a dabbler in programming I have to say that poor documentation is not
excused by the availability of sources. If the sources are that
informative than relevant portions should be pasted into the docs
(or, better, marked up in some way that a doc generator and extract
them into the officials docs).
If the docs need to refer to the sources so often, perhaps we should
re-write the docs so that every page has hyperlink references to the
relevant source modules. Making someone manually hunt down information
from alternative sources is a great way to frustrate them!
> Many modules have a little blurb at the top that gives an example of their
Sounds like a job for doc strings. Moreover it sounds like a job
for an automated docstring processing (http://docutils.sourceforge.net/
> from imaplib.py:
> Instantiate with: IMAP4([host[, port]])
> host - host's name (default: localhost);
> port - port number (default: standard IMAP4 port).
> All IMAP4rev1 commands are supported by methods of the same
> name (in lower-case).
More importantly this module *does* give a 10 line code example:
It would be nice if it also explained some of the magic numbers
and strings in comments or in some text around the example:
Why M.search(None, 'ALL')
and why '(RFC822)' as the 2nd arg in the M.fetch()
Okay, now I go back to another page and read about the .search() and
.fetch() methods. Hmmm, .fetch() lists UID and BODY, no reference to
RFC822 and not hint as to where I'd find any other valid strings here;
I guess I have to go read the IMAP RFCs, where are those? Ooops, another
trip to Google!
<flame mode="rant" context="off">Google would be so necessary if
HTML authors would link to other relevant sources!</flame>
If we expect people to read the RFCs in order to use the bloody module
than we ought to at least provide the link to the RFC! (Putting a copy
on our own servers to ensure a stable URL is Okay).
The documentation of the .search() method also neglects to make any
mention of 'ALL' though we might expect that to be the MOST COMMON
CRITERIUM! (at least for someone who's just trying to learn the
I'm only picking on this particular page because you brought it up.
Actually it's one of the better pages because it does include an
example. The pty module is one of the worst. Pipe in if you were
able to use the pty module just from the docs!
Python includes the broadest wealth of modules I've never seen in a
programming language. Docstrings are a stroke of pure genius. The
interpreter's readline and rlcompleter support is wonderful for beginners
and dabblers --- and rlcompleter2 is EVEN BETTER (Guido --- please
merge that! :) ). The docs are Okay --- but could be ALOT better.
I'd love to see a way for members of the community (even duffers and dabblers
like me) to submit doc enhancement suggestions and requests directly through
the online HTML documentation (similar to the PHP system at:
http://www.php.net/docs.php). Of course more well-known, trusted members
of the community should have the power to editing, revise, even throw out
One danger I see in __doc__ is the various ways in which they are being
overloaded. doctest seems reasonable; a small sample usage that also
serves as an automated test suite. (Yes, I have read the little Soapbox
note at: http://www.python.org/doc/current/lib/node130.html) However
some of the programming by contract (http://www.wayforward.net/pycontract/ )
starts to worry me.
How will doctest and pycontract play together? How will docutils
handle the results? What will be the next clever uses of __doc__
members? How will it mesh with all the other uses? It sounds
like one might very reasonably argue that these other uses should
have their own standards (or conventions) with their own namespaces:
__testsuite__ and __contract__ (or __pre-condition__, __post-condition__,
and __invariants__), for example.
(Even that use is *almost* documentation so I can stretch a little to
see it --- and it is a nice hack. However, if something like pycontract
is ever accepted into the standard libraries, I'd suggest it be given
it's own __ namespace)
More information about the Python-list