Open Stack

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/20140225/ac605e53/attachment.html>