Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!news.mixmin.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed4a.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.004 X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'example:': 0.03; 'interpreter': 0.05; 'subject:Python': 0.06; 'arguments': 0.09; 'feature.': 0.09; 'output,': 0.09; 'python': 0.11; 'suggest': 0.14; "cc'ing": 0.16; 'material)': 0.16; "module's": 0.16; 'stumbled': 0.16; 'unix,': 0.16; 'unlikely': 0.16; 'url.': 0.16; 'url:urllib': 0.16; 'urllib': 0.16; 'ignore': 0.16; 'wrote:': 0.18; 'library': 0.18; 'module': 0.19; 'basically': 0.19; 'thu,': 0.19; 'meant': 0.20; 'not,': 0.20; 'seems': 0.21; '(the': 0.22; 'import': 0.22; 'email addr:gmail.com>': 0.22; 'certainly': 0.24; 'refers': 0.24; 'skip': 0.24; 'source': 0.25; '>': 0.26; 'header:In-Reply-To:1': 0.27; 'feature': 0.29; 'am,': 0.29; 'nature': 0.30; 'message-id:@mail.gmail.com': 0.30; "i'm": 0.30; 'asked': 0.31; 'code': 0.31; 'software,': 0.31; 'file': 0.32; 'open': 0.33; 'url:python': 0.33; "can't": 0.35; 'one,': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'version': 0.36; 'like,': 0.36; 'subject:skip:d 10': 0.36; "i'll": 0.36; 'url:org': 0.36; 'skip:& 10': 0.38; 'nov': 0.38; 'url:library': 0.38; 'to:addr:python-list': 0.38; 'does': 0.39; 'to:addr:python.org': 0.39; 'either': 0.39; 'skip:u 10': 0.60; 'contributing': 0.60; 'ago,': 0.61; 'simply': 0.61; 'name': 0.63; 'here': 0.66; 'response.': 0.68; '20,': 0.68; 'prompt': 0.68; 'overall': 0.69; 'online': 0.71; 'inline': 0.74; 'brief,': 0.84; "else's": 0.84; 'improved.': 0.84 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=VxE49Vw9QZw8vOx0QV5k6xFUFPcslTlIUQxkbYJUUlI=; b=XK6L5wZFTh7TTbXsTmPhMh7NOr1FpozOukMyhqMAkgpgq7aRCN7iDafvxxy8TJiPiA wql9MaPRVFE8X5eNO8xqno2M5xhjOPU3sS/eHvDLW1ykMcHMDqi8KjNjB5KiodJYKxTI FvA0qXDqHw4ZGo6JbEg8mhmp5R/Jkutphye6mpmFVZ29RUfArb8NKVAHGYgz2JJ9ObGP NW1mllz8GcrWYhvP78l4ZYEXe1RAshW1BLsmUSJuHwb08AagP4Ts/JpIGTbyL5mCvCys JLhd/ygMQFFl4hH/Kzv8Bdc529FD2cYwcCa4yTlSQqVHrZ6rAnTPYiXL6Og6+ozjHvww 6Lwg== MIME-Version: 1.0 X-Received: by 10.42.61.18 with SMTP id s18mr1270043ich.73.1416503908693; Thu, 20 Nov 2014 09:18:28 -0800 (PST) In-Reply-To: <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com> References: <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com> Date: Thu, 20 Nov 2014 11:18:28 -0600 Subject: Re: Python docs disappointing From: Skip Montanaro To: Python Content-Type: multipart/alternative; boundary=20cf30223e894cfea305084d84e6 X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 119 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1416503918 news.xs4all.nl 2860 [2001:888:2000:d::a6]:58688 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:81094 --20cf30223e894cfea305084d84e6 Content-Type: text/plain; charset=UTF-8 On Thu, Nov 20, 2014 at 9:54 AM, 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 --20cf30223e894cfea305084d84e6 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable

= On Thu, Nov 20, 2014 at 9:54 AM, <jstnms123@gmail.com> wr= ote:
> 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. (T= hey also seem to misunderstand the nature of contributing to open source so= ftware, 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. O= ne, pydoc just assembles the documentation strings for the item you asked f= or. Python has both inline documentation (meant to be brief, quick referenc= e material) and long form documentation (the library and reference document= ation, as well as the tutorial.) Pydoc just extracts what is available at t= he 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 inten= t of the urllib module?". Despite its admitted brevity, note that if y= ou 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 a= nd refers you to the long form online documentation:

Help on module urllib:

=
NAME
=C2=A0 =C2=A0 urllib - Open an a= rbitrary URL.

FILE<= /div>
=C2=A0 =C2=A0 /opt/TWWfsw/python27/lib/python2.7/urllib.py

MODULE DOCS
=C2=A0 =C2=A0 http= ://docs.python.org/library/urllib

DESCRIPTION
<= font face=3D"monospace">=C2=A0 =C2=A0 ...

I in no way mean to suggest th= at the documentation can't be improved. I'm simply pointing out tha= t the documentation is almost certainly better than kj and jstnms123 give t= he 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 i= s missing this feature.

Skip

<= /div>
--20cf30223e894cfea305084d84e6--