<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <span dir="ltr"><<a href="mailto:stephen@xemacs.org" target="_blank">stephen@xemacs.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="im">Eli Bendersky writes:<br>
<br>
 > IMHO the right way to think about it is that the .rst files are by<br>
 > far the more important documentation.  Sometimes we forget that<br>
 > most Python programmers are people who won't go into the source<br>
<br>
</div>Why "source"?  The whole point of docstrings is that they are *not*<br>
comments found only in the source, but available at run time. In fact,<br>
programmers who also use environments like Lisp or R (not to forget<br>
Idle) will reach for "help(mean)", and that works fine for Steven,<br>
because he provides such nice docstrings.<br>
<br>
Some people prefer to write separate manuals, and some modules<br>
*should* be documented that way because their internal complexity or<br>
whatever.  That's true, but I would hope authors who prefer "literate<br>
programming" (or the poor man's lit prog that is writing only<br>
docstrings) are encouraged to do so when appropriate.<br>
<br>
Of course, like any other contribution, since that style is *not*<br>
currently supported by python-dev, they'd be asked to step up and<br>
support it themselves -- if a user reports the docs won't build, they<br>
need to address that like they would a build bug in the code.</blockquote><div> </div></div>Authors writing 3rd party packages can do what they want.<br><br></div><div class="gmail_extra">But for the stdlib it's been settled for ages: docstrings should be concise (but not cryptic(*)), longer documentation go into the separately written text for <a href="http://docs.python.org">docs.python.org</a>.<br>

<br></div><div class="gmail_extra">(*) This is too concise to my taste:<br>$ ls -?<br>ls: illegal option -- ?<br>usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]<br>$ <br><br clear="all"></div><div class="gmail_extra">

<br>-- <br>--Guido van Rossum (<a href="http://python.org/~guido">python.org/~guido</a>)
</div></div>