I prefer how the separate lines look, but it results in having leading/trailing whitespaces in the docstring. This may not be an issue, but it's something I've had to work around in the past.
On Fri, Oct 21, 2011 at 12:37 PM, Jay Pipes <jaypi...@gmail.com> wrote: > ++ > > I also believe the requirements to: > > a) Have a single-line <80 characters brief description AND a long > description > b) Start the description on the same line as the beginning """ > > are silly. > > I think this: > > """ > This is a description, long or short, of what the thing > does. It doesn't have to have any particular length or > lack of length > > :param some_param: Description of param > """ > > Is more readable than: > > > """This is a description, artificially limited to 80 characters for som > > This is a longer description that doesn't really need to be here. > > :param some_param: Description of param > > """ > > -jay > > On Fri, Oct 21, 2011 at 1:29 PM, Kevin L. Mitchell > <kevin.mitch...@rackspace.com> wrote: > > Our HACKING includes this requirement for multiline docstrings: > > > > [...] After you have finished your descriptions add an extra > > newline and close the quotations. > > > > I propose that we remove this line and requirement from HACKING. We > > don't have to adjust all the docstrings to remove an extraneous space, > > but we should not require that it be here. Below is my defense: > > > > This requirement has never made sense to me, and there does seem to be > > some disagreement within nova about following this. So, for more > > insight, I went and read PEP 257, and discovered this rationale: > > > > 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. > > > > (The indicated footnote is just an explanation of the term "BDFL".) > > > > So, the first point I want to make is that this was a recommendation of > > PEP 257, rather than a requirement. The second point is that it was due > > to a limitation of the fill-paragraph command of a single editor. And > > the third point is that the editor in question, which happens to be my > > editor of choice, no longer has this limitation, at least in recent > > versions--fill-paragraph on docstrings terminated by triple-quotes > > ignores the triple-quotes. Therefore, I believe the recommendation no > > longer has any substance behind it, and so it should no longer be > > required of HACKING-conforming code for nova. > > -- > > Kevin L. Mitchell <kevin.mitch...@rackspace.com> > > > > This email may include confidential information. If you received it in > error, please delete it. > > _______________________________________________ > > Mailing list: https://launchpad.net/~openstack > > Post to : openstack@lists.launchpad.net > > Unsubscribe : https://launchpad.net/~openstack > > More help : https://help.launchpad.net/ListHelp > > > > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : openstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp >
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
