[Python-Dev] Best practice for documentation for std lib

[Brett Cannon]

On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano <steve at pearwood.info>wrote:

> On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote:
> > On Sun, 22 Sep 2013 13:13:04 +1000
> > Steven D'Aprano <steve at pearwood.info> wrote:
> > > Hi all,
> > >
> > > I have a question about how I should manage documentation for the
> > > statistics module for Python 3.4. At the moment, I have extensive
> > > docstrings in the module itself. I don't believe anyone has flagged
> that
> > > as "too much information" in a code review, so I'm going to assume that
> > > large docstrings will be acceptable.
> >
> > Related question: do the extensive docstrings make "help(stats)"
> > painful to browse through?
>
> Not to me. I can page through help(statistics) with 18 presses of the
> space bar, versus 20 for random or 45 for unittest. (29 lines per page.)
>
> Admittedly statistics has fewer functions/classes than random, but I
> find that fewer, larger pieces of documentation are easier to read than
> lots of tiny one-line mentions that don't actually tell you anything.
> E.g. from unittest:
>
>      |  Methods defined here:
>      |
>      |  __init__(self, stream, descriptions, verbosity)
>      |
>      |  addError(self, test, err)
>      |
>      |  addExpectedFailure(self, test, err)
>      |
>      |  addFailure(self, test, err)
>      |
>      |  addSkip(self, test, reason)
>
> and so on for nearly a page. unittest is also packed with many, many
> one-line methods listed as deprecated.
>
> I admit I'm a bit of a stats and maths junkie, I read stats text books
> for fun. So perhaps I'm not the best person to judge how much
> information is too much information. Comments to the tracker please:
>
> http://bugs.python.org/issue18606


The rule of thumb I go by is the docstring should be enough to answer the
question "what args does this thing take and what does it do in general to
know it's the function I want and another one in the same module?" quickly
and succinctly; i.e. just enough so that help() reminds you about details
for a module you are already familiar with that might come up while at the
interpreter prompt. Everything else -- in-depth discussion of the
algorithms, extra examples, why you want to use this function, etc. -- all
go in the .rst docs.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/669ee320/attachment-0001.html>