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