On Feb 25, 2014, at 4:08 PM, Joe Gordon <joe.gord...@gmail.com> wrote:
> On Mon, Feb 24, 2014 at 4:56 PM, Ziad Sawalha > <ziad.sawa...@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? https://review.openstack.org/#/c/73515/4/heat/api/aws/exception.py > Style should never ever be enforced by a human, Agreed. I’d be happy to include a PEP-257 plugin to flake8 (or a change to the hacking library) customized for our rules in the hacking doc. I’m actually testing a fork of a flake8 plugin here: https://github.com/ziadsawalha/flake8_docstrings > if the code passed > the pep8 job, then its acceptable. PEP-8 does not cover this. PEP-257 combined with the our OpenStack hacking standards. >> >> 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 >> > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev