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

[Ziad Sawalha]

Thanks, Guido.

I’ll follow up with updates to common tools as I come across them (ex. pep257: https://github.com/GreenSteam/pep257/pull/64).

Ziad


On Feb 28, 2014, at 11:53 AM, Guido van Rossum <guido at python.org<mailto:guido at python.org>> wrote:

Updated!


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


On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido at python.org<mailto: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<mailto:ziad.sawalha at rackspace.com>> wrote:

On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce at leapyear.org<mailto: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<mailto: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<mailto: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<mailto: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<http://python.org/~guido>)



--
--Guido van Rossum (python.org/~guido<http://python.org/~guido>)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140303/377693d1/attachment.html>