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.
-- Ed Leafe
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
