On Fri, Oct 21, 2011 at 2:17 PM, Ed Leafe <ed.le...@rackspace.com> wrote: > On Oct 21, 2011, at 12:37 PM, 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. > > Unfortunately, many tools that auto-generate documentation from > docstrings rely on this convention. I fully agree that it makes for ugly > docstrings, but I believe that the purpose is not to make the source code > more readable. That's also the reason for the (usually) useless listing of > :param elements - those should only be documented if there is something funky > about them, and even then you should first reconsider your use cases and > design if you can't remove the funkiness.
The original poster complained that we shouldn't be doing our docstrings just because an old version of Emacs didn't like a lack of a newline. I say we shouldn't make our docstring style dependent on broken documenation "generators" that we don't even use. Documentation is to be read. The more readable, the better the documentation, IMHO. -jay _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
