openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

On Fri, Oct 21, 2011 at 2:17 PM, Ed Leafe <ed.leafe@xxxxxxxxxxxxx> 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