Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #81094

Re: Python docs disappointing

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

On Thu, Nov 20, 2014 at 9:54 AM, <jstnms123@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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Re: Python docs disappointing jstnms123@gmail.com - 2014-11-20 07:54 -0800
  Re: Python docs disappointing Joel Goldstick <joel.goldstick@gmail.com> - 2014-11-20 11:51 -0500
    Re: Python docs disappointing albert@spenarnc.xs4all.nl (Albert van der Horst) - 2014-12-04 10:27 +0000
      Re: Python docs disappointing Chris Angelico <rosuav@gmail.com> - 2014-12-04 21:37 +1100
      Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-12-04 22:46 +1100
      Re: Python docs disappointing jtan <admin@grails.asia> - 2014-12-05 07:33 +0800
      Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-12-04 16:57 -0700
  Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-11-20 09:51 -0700
  Re: Python docs disappointing Skip Montanaro <skip.montanaro@gmail.com> - 2014-11-20 11:18 -0600
  Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-20 23:10 +0000
    Re: Python docs disappointing Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-11-20 23:22 +0000
  Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-11-21 10:29 +1100
    Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-21 16:35 +0000

csiph-web