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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
