I prefer how the separate lines look, but it results in having leading/trailing whitespaces in the docstring. This may not be an issue, but it's something I've had to work around in the past.<br><br><div class="gmail_quote">
On Fri, Oct 21, 2011 at 12:37 PM, Jay Pipes <span dir="ltr"><<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
++<br>
<br>
I also believe the requirements to:<br>
<br>
a) Have a single-line <80 characters brief description AND a long description<br>
b) Start the description on the same line as the beginning """<br>
<br>
are silly.<br>
<br>
I think this:<br>
<br>
"""<br>
This is a description, long or short, of what the thing<br>
does. It doesn't have to have any particular length or<br>
lack of length<br>
<br>
:param some_param: Description of param<br>
"""<br>
<br>
Is more readable than:<br>
<br>
<br>
"""This is a description, artificially limited to 80 characters for som<br>
<br>
This is a longer description that doesn't really need to be here.<br>
<br>
:param some_param: Description of param<br>
<br>
"""<br>
<br>
-jay<br>
<br>
On Fri, Oct 21, 2011 at 1:29 PM, Kevin L. Mitchell<br>
<<a href="mailto:kevin.mitchell@rackspace.com">kevin.mitchell@rackspace.com</a>> wrote:<br>
> Our HACKING includes this requirement for multiline docstrings:<br>
><br>
>        [...] After you have finished your descriptions add an extra<br>
>        newline and close the quotations.<br>
><br>
> I propose that we remove this line and requirement from HACKING.  We<br>
> don't have to adjust all the docstrings to remove an extraneous space,<br>
> but we should not require that it be here.  Below is my defense:<br>
><br>
> This requirement has never made sense to me, and there does seem to be<br>
> some disagreement within nova about following this.  So, for more<br>
> insight, I went and read PEP 257, and discovered this rationale:<br>
><br>
>        The BDFL [3] recommends inserting a blank line between the last<br>
>        paragraph in a multi-line docstring and its closing quotes,<br>
>        placing the closing quotes on a line by themselves. This way,<br>
>        Emacs' fill-paragraph command can be used on it.<br>
><br>
> (The indicated footnote is just an explanation of the term "BDFL".)<br>
><br>
> So, the first point I want to make is that this was a recommendation of<br>
> PEP 257, rather than a requirement.  The second point is that it was due<br>
> to a limitation of the fill-paragraph command of a single editor.  And<br>
> the third point is that the editor in question, which happens to be my<br>
> editor of choice, no longer has this limitation, at least in recent<br>
> versions--fill-paragraph on docstrings terminated by triple-quotes<br>
> ignores the triple-quotes.  Therefore, I believe the recommendation no<br>
> longer has any substance behind it, and so it should no longer be<br>
> required of HACKING-conforming code for nova.<br>
> --<br>
> Kevin L. Mitchell <<a href="mailto:kevin.mitchell@rackspace.com">kevin.mitchell@rackspace.com</a>><br>
><br>
> This email may include confidential information. If you received it in error, please delete it.<br>
> _______________________________________________<br>
> Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
> Post to     : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
> Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
> More help   : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
><br>
<br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to     : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help   : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</blockquote></div><br>