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
--
Steven
_______________________________________________
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
