<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sun, Sep 22, 2013 at 5:31 PM, 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:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="im">On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote:<br>
<br>
> Authors writing 3rd party packages can do what they want.<br>
><br>
> But for the stdlib it's been settled for ages: docstrings should be concise<br>
> (but not cryptic(*)), longer documentation go into the separately written<br>
> text for <a href="http://docs.python.org" target="_blank">docs.python.org</a>.<br>
<br>
</div>It is the second half that I'm not sure about. How long is *too long*<br>
for a doc string? My own preference is to err on the side of too much<br>
rather than too little, since I live by help() and only fall back on the<br>
web documentation when I really must.<br></blockquote><div><br></div><div>I guess preferences differ. I like reading the source, and often I find overly long docstrings distracting.<br><br></div><div>If I had the final word, I'd recommend using the current docstrings as the .rst contents and replacing the docstrings with the 1-2 line function descriptions from the PEP, e.g.:<br>

<br>            * median(data) -> median (middle value) of data, taking the<br>              average of the two middle values when there are an even<br>              number of values.<br><br></div><div>But omitting the signature proper, and replacing "->" with "Returns" or "Returns the". E.g.<br>

<br></div><div><span style="font-family:courier new,monospace">    def median(data):<br></span></div><div><span style="font-family:courier new,monospace">        """Returns the median (middle value) of data, taking the<br>

           average of the two middle values when there are an even<br>           number of values.<br>        """<br>        ...</span><br></div><div><br></div><div>I'd personally also rewrite them all so that the first line of the docstring is a phrase that can stand by itself, as I describe in PEP 8, but this is used only sporadically in the stdlib.<br>

</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Rather than keep talking in generalities, I'll come up with a first<br>
draft rst document over the next week or so, put it on the tracker, and<br>
wait for some concrete feedback on that.<br>
<br>
What's the policy about linking to external content from the web docs?<span class=""></span><br></blockquote></div><br></div><div class="gmail_extra">If it's for background information or an introduction to the theory  that's fine. If it's as a substitute for proper documentation of an API I'd frown upon it. Someone in a spaceship on its way to Mars  with a copy of <a href="http://docs.python.org">docs.python.org</a> should have no problems using the library, as long as they are familiar with the basic theory such as might be explained on Wikipedia (of which the spaceship would of course also have a copy :-).<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>