Python docs disappointing

[Skip Montanaro]

On Thu, Nov 20, 2014 at 9:54 AM, <jstnms123 at gmail.com> wrote:

> > Here is an *entirely typical* example: on some Unix, try
> >
> > % pydoc urllib
>

I don't know who "kj" is, and jstnms123 seems to be basically off his
rocker, so I won't try cc'ing either of them. (They also seem to
misunderstand the nature of contributing to open source software, but I'll
ignore that.)

Hopefully I'm not duplicating someone else's response. I just stumbled on
this thread. A couple things to note. One, pydoc just assembles the
documentation strings for the item you asked for. Python has both inline
documentation (meant to be brief, quick reference material) and long form
documentation (the library and reference documentation, as well as the
tutorial.) Pydoc just extracts what is available at the interpreter prompt
if you execute

import urllib
help(urllib)

That is meant to answer quick questions like, "what arguments does
urllib.urlopen accept?", not, "what's the overall intent of the urllib
module?". Despite its admitted brevity, note that if you ask pydoc for a
module's documentation, that at the very top of its output, it also
identifies the location of the source code on your system and refers you to
the long form online documentation:

Help on module urllib:

NAME
    urllib - Open an arbitrary URL.

FILE
    /opt/TWWfsw/python27/lib/python2.7/urllib.py

MODULE DOCS
    http://docs.python.org/library/urllib

DESCRIPTION
    ...


I in no way mean to suggest that the documentation can't be improved. I'm
simply pointing out that the documentation is almost certainly better than
kj and jstnms123 give the authors credit for. I added that particular
feature to the pydoc module over ten years ago, so I know it is highly
unlikely your version of pydoc is missing this feature.

Skip
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20141120/f441224f/attachment.html>