Open Stack

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?

Style should never ever be enforced by a human, if the code passed
the pep8 job, then its acceptable.

>
> 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
>