On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano <st...@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 <st...@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.
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
