+1 On Oct 21, 2011, at 10:37 AM, Jay Pipes 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 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
