openstack team mailing list archive

[Ed Leafe <ed.leafe@xxxxxxxxxxxxx>]

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.