Open Stack

On Feb 25, 2014, at 4:08 PM, Joe Gordon <joe.gordon0 at gmail.com> wrote:

> On Mon, Feb 24, 2014 at 4:56 PM, Ziad Sawalha
> <ziad.sawalha at rackspace.com> wrote:
>> Seeking some clarification on the OpenStack hacking guidelines for
>> multi-string docstrings.
>> 
>> Q: In OpenStack projects, is a blank line before the triple closing quotes
>> recommended (and therefore optional - this is what PEP-257 seems to
>> suggest), required, or explicitly rejected (which could be one way to
>> interpret the hacking guidelines since they omit the blank line).
>> 
>> This came up in a commit review, and here are some references on the topic:
> 
> Link?

https://review.openstack.org/#/c/73515/4/heat/api/aws/exception.py

> Style should never ever be enforced by a human,

Agreed. I’d be happy to include a PEP-257 plugin to flake8 (or
a change to the hacking library) customized for our rules in the
hacking doc.

I’m actually testing a fork of a flake8 plugin here: https://github.com/ziadsawalha/flake8_docstrings

> if the code passed
> the pep8 job, then its acceptable.

PEP-8 does not cover this. PEP-257 combined with the our OpenStack hacking standards.

>> 
>> Quoting PEP-257: "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."
>> 
>> Sample from pep257 (with extra blank line):
>> 
>> def complex(real=0.0, imag=0.0):
>>    """Form a complex number.
>> 
>>    Keyword arguments:
>>    real -- the real part (default 0.0)
>>    imag -- the imaginary part (default 0.0)
>> 
>>    """
>>    if imag == 0.0 and real == 0.0: return complex_zero
>>    ...
>> 
>> 
>> The multi-line docstring example in
>> http://docs.openstack.org/developer/hacking/ has no extra blank line before
>> the ending triple-quotes:
>> 
>> """A multi line docstring has a one-line summary, less than 80 characters.
>> 
>> Then a new paragraph after a newline that explains in more detail any
>> general information about the function, class or method. Example usages
>> are also great to have here if it is a complex class for function.
>> 
>> When writing the docstring for a class, an extra line should be placed
>> after the closing quotations. For more in-depth explanations for these
>> decisions see http://www.python.org/dev/peps/pep-0257/
>> 
>> If you are going to describe parameters and return values, use Sphinx, the
>> appropriate syntax is as follows.
>> 
>> :param foo: the foo parameter
>> :param bar: the bar parameter
>> :returns: return_type -- description of the return value
>> :returns: description of the return value
>> :raises: AttributeError, KeyError
>> """
>> 
>> Regards,
>> 
>> Ziad
>> 
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev