openstack team mailing list archive

[Chris Behrens <chris.behrens@xxxxxxxxxxxxx>]

+1 

On Oct 21, 2011, at 10:37 AM, Jay Pipes 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

This email may include confidential information. If you received it in error, please delete it.