Open Stack

Guido kindly updated PEP-257 for us[1]. So now the hacking guide content accurately matches PEP-257 (no extra line required at the end of a multi-line docstring).

This alone should resolve the patch and comments that initiated this discussion.

With regards to automating the checks and gates, we’ll experiment with gating on this using the flake8 pep257 plugin[2] and submit the jobs that come out of that to stackforge. There are still some patches[3] to get in to pep257 and the flake8 plugin (for PEP-257 and for compatibility with the latest pep8 version).

Z

[1] https://codereview.appspot.com/69870043
[2] https://pypi.python.org/pypi/flake8-docstrings/0.1.4
[3] https://github.com/GreenSteam/pep257/pull/64


On Feb 24, 2014, at 6:56 PM, Ziad Sawalha <ziad.sawalha at rackspace.com<mailto: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:

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140303/ce358c54/attachment.html>