<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">
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).
<div><br>
</div>
<div>This alone should resolve the patch and comments that initiated this discussion.<br>
<div><br>
</div>
<div>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).<br>
<div><br>
</div>
<div>Z</div>
<div><br>
</div>
<div>[1] <a href="https://codereview.appspot.com/69870043">https://codereview.appspot.com/69870043</a></div>
<div>[2] <a href="https://pypi.python.org/pypi/flake8-docstrings/0.1.4">https://pypi.python.org/pypi/flake8-docstrings/0.1.4</a></div>
<div>[3] <a href="https://github.com/GreenSteam/pep257/pull/64">https://github.com/GreenSteam/pep257/pull/64</a></div>
<div><br>
</div>
<div><br>
<div>
<div>On Feb 24, 2014, at 6:56 PM, Ziad Sawalha <<a href="mailto:ziad.sawalha@rackspace.com">ziad.sawalha@rackspace.com</a>> wrote:</div>
<br class="Apple-interchange-newline">
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">
Seeking some clarification on the OpenStack hacking guidelines for multi-string docstrings.
<div><br>
</div>
<div>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).<br>
<div><br>
</div>
<div>This came up in a commit review, and here are some references on the topic:</div>
<div><br>
</div>
<div>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.”</div>
<div><br>
</div>
<div>Sample from pep257 (with extra blank line):</div>
<div>
<pre class="literal-block" style="padding: 10px; font-size: 14px; background-color: rgb(224, 224, 255); line-height: 17.8231201171875px; position: static; z-index: auto;">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
...</pre>
<div><br>
</div>
</div>
<div>The multi-line docstring example in <a href="http://docs.openstack.org/developer/hacking/">http://docs.openstack.org/developer/hacking/</a> has no extra blank line before the ending triple-quotes:</div>
<div>
<pre style="overflow: auto; padding: 10px; background-color: rgb(255, 255, 255); color: rgb(85, 85, 85); line-height: 1.2em; border: 1px solid rgb(198, 201, 203); font-size: 1.1em; margin-top: 1.5em; margin-bottom: 1.5em; -webkit-box-shadow: rgb(216, 216, 216) 1px 1px 1px;"><span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">"""A multi line docstring has a one-line summary, less than 80 characters.</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">Then a new paragraph after a newline that explains in more detail any</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">general information about the function, class or method. Example usages</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">are also great to have here if it is a complex class for function.</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">When writing the docstring for a class, an extra line should be placed</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">after the closing quotations. For more in-depth explanations for these</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">decisions see <a href="http://www.python.org/dev/peps/pep-0257/">http://www.python.org/dev/peps/pep-0257/</a></span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">If you are going to describe parameters and return values, use Sphinx, the</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">appropriate syntax is as follows.</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">:param foo: the foo parameter</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">:param bar: the bar parameter</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">:returns: return_type -- description of the return value</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">:returns: description of the return value</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">:raises: AttributeError, KeyError</span>
<span class="sd" style="color: rgb(64, 112, 160); font-style: italic;">"""</span></pre>
<div>Regards,</div>
</div>
</div>
<div><br>
</div>
<div>Ziad</div>
</div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</body>
</html>