openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

++

I also believe the requirements to:

a) Have a single-line <80 characters brief description AND a long description
b) Start the description on the same line as the beginning """

are silly.

I think this:

"""
This is a description, long or short, of what the thing
does. It doesn't have to have any particular length or
lack of length

:param some_param: Description of param
"""

Is more readable than:


"""This is a description, artificially limited to 80 characters for som

This is a longer description that doesn't really need to be here.

:param some_param: Description of param

"""

-jay

On Fri, Oct 21, 2011 at 1:29 PM, Kevin L. Mitchell
<kevin.mitchell@xxxxxxxxxxxxx> wrote:
> Our HACKING includes this requirement for multiline docstrings:
>
>        [...] After you have finished your descriptions add an extra
>        newline and close the quotations.
>
> I propose that we remove this line and requirement from HACKING.  We
> don't have to adjust all the docstrings to remove an extraneous space,
> but we should not require that it be here.  Below is my defense:
>
> This requirement has never made sense to me, and there does seem to be
> some disagreement within nova about following this.  So, for more
> insight, I went and read PEP 257, and discovered this rationale:
>
>        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.
>
> (The indicated footnote is just an explanation of the term "BDFL".)
>
> So, the first point I want to make is that this was a recommendation of
> PEP 257, rather than a requirement.  The second point is that it was due
> to a limitation of the fill-paragraph command of a single editor.  And
> the third point is that the editor in question, which happens to be my
> editor of choice, no longer has this limitation, at least in recent
> versions--fill-paragraph on docstrings terminated by triple-quotes
> ignores the triple-quotes.  Therefore, I believe the recommendation no
> longer has any substance behind it, and so it should no longer be
> required of HACKING-conforming code for nova.
> --
> Kevin L. Mitchell <kevin.mitchell@xxxxxxxxxxxxx>
>
> This email may include confidential information. If you received it in error, please delete it.
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>