[Python-Dev] Best practice for documentation for std lib

[Guido van Rossum]

On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings <larry at hastings.org> wrote:

>  On 09/23/2013 03:44 AM, Guido van Rossum wrote:
>
>  On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy at udel.edu> wrote:
>
>> I am gradually changing Idle docstrings, though only Idle developers will
>> ever see them. Writing a 60 char summary forces a clear understanding of
>> the function.
>
>
>  Glad you like it. I still do, too, but I've given up hope to convince
> all core developers to stick to this style. :-(
>
>
> ... Argument Clinic to the rescue?  Since the last time this subject came
> up, Clinic has started enforcing a summary line in docstrings.  I didn't
> realize it had to be 60 columns though, should I add that?  Is the entire
> docstring supposed to be 60 columns max?
>

I think 60 is just a guideline. In stdlib .py source code I want it not to
extend beyond the 79th column (see recent PEP 8 argument). For a typical
class, where the docstring is indented 4 spaces, that leaves 72 characters
for the summary line (including a final period!). For a method it's 68 due
to the extra indent.

FWIW I also prefer having the summary line on the same line as the opening
""":

def foo():
    """This is the summary.

    This is the rest.
    """


> p.s. status update: AC is done enough to be worth considering checking
> in.  Now I have to finish the PEP and write the documentation.
>

-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130923/8acbe2fd/attachment.html>