(original) (raw)
On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings <larry@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@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)