[Python-ideas] PEP-257: drop recommendation for extra line at end of multi-line docstring

[Guido van Rossum]

Updated!


On Thu, Feb 27, 2014 at 8:58 PM, Ziad Sawalha <ziad.sawalha at rackspace.com>wrote:

>  Approved :-)
>
>
> On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido at python.org> wrote:
>
>   How about this patch? http://codereview.appspot.com/69870043
>
>
> On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha at rackspace.com>wrote:
>
>>
>>  On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce at leapyear.org> wrote:
>>
>>   To clarify are you asking to delete the recommendation of a blank line
>> or the entire recommendation?
>>
>>  That is are you suggesting the recommendation change to
>>
>>  "It is recommended to place the closing quotes on a line by themselves."
>>
>>
>>  That's right. I just want to get rid of the recommendation for the
>> blank line.
>>
>>   I think deleting it completely is a bad idea as otherwise it's hard to
>> see where the docstring ends and the code begins, especially when using
>> doctest.
>>
>>  --- Bruce
>>  Learn how hackers think: http://j.mp/gruyere-security
>>  https://www.linkedin.com/in/bruceleban
>>
>>
>>
>> On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha at rackspace.com
>> > wrote:
>>
>>> PEP-257 includes this recommendation:
>>>
>>> "The BDFL [3] recommends inserting a blank line between the last
>>> paragraph in a multi-line
>>> docstring and its closing quotes, placing the closing quotes on a line
>>> by themselves. This way,
>>> Emacs' fill-paragraph command can be used on it."
>>>
>>> I believe emacs no longer has this limitation. "If you do fill-paragraph
>>> in emacs in Python mode
>>> within a docstring, emacs already ignores the closing triple-quote.  In
>>> fact, the most recent version
>>> of emacs supports several different docstring formatting styles and
>>> gives you the ability to switch
>>> between them." - quoting Kevin L. Mitchell who is more familiar with
>>> emacs than I am.
>>>
>>> I'm considering removing that recommendation and updating some of the
>>> examples in PEP-257,
>>> but I'd like some thoughts from this group before I submit the patch.
>>> Any thoughts or references to
>>> conversations that may have already been had on this topic?
>>>
>>> Regards,
>>> Ziad
>>> _______________________________________________
>>> Python-ideas mailing list
>>> Python-ideas at python.org
>>> https://mail.python.org/mailman/listinfo/python-ideas
>>> Code of Conduct: http://python.org/psf/codeofconduct/
>>>
>>
>>
>> _______________________________________________
>> Python-ideas mailing list
>> Python-ideas at python.org
>> https://mail.python.org/mailman/listinfo/python-ideas
>> Code of Conduct: http://python.org/psf/codeofconduct/
>>
>
>
>
> --
> --Guido van Rossum (python.org/~guido)
>
>


-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140228/37cb270f/attachment-0001.html>