<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano <span dir="ltr"><<a href="mailto:steve@pearwood.info" target="_blank">steve@pearwood.info</a>></span> wrote:<br>

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

</div></div></div>