openstack team mailing list archive

[Josh Kearney <josh@xxxxxxx>]

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.

On Fri, Oct 21, 2011 at 12:37 PM, Jay Pipes <jaypipes@xxxxxxxxx> wrote:

> ++
>
> 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
> >
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>