[Python-Dev] query: docstring formatting in python distutils code

[Barry Warsaw]

On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote:

>On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou <solipsis at pitrou.net>
>wrote:
>> On Wed, 7 Jul 2010 14:12:17 -0400
>> Barry Warsaw <barry at python.org> wrote:
>>> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
>>>
>>> >Overall, I think that we can make stdlib docstrings valid reST --
>>> >even if it's reST without much markup -- but valid, so that people
>>> >pulling in stdlib doc- strings into Sphinx docs won't get ugly
>>> >warnings.
>>> >
>>> >What I would *not* like to see is heavy markup and Sphinx
>>> >specifics -- that would only make sense if we included the
>>> >docstrings in the docs, and I don't see that coming.
>>>
>>> Does it make sense to add (reST-style) epydoc markup for API
>>> signatures? E.g.
>>
>> It really looks ugly (and annoying to decipher) when viewed in plain
>> text.
>
>I agree. And it is highly repetitive since the signature information
>is right there already. All of that info in those annotations can
>easily be written in paragraph form if needed and honestly would read
>better to my eyes.

I actually find it easier to glean the signature details from a regularized
docstring than from prose.  Especially for autogenerated API documentation,
the formal specification lends a consistency to the output that prose doesn't
often provide.  IME, there isn't much (unnecessary) repeating yourself.

Either way, we need to be diligent in accurately describing the signature and
semantics of our APIs.

-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100709/47b1d944/attachment.pgp>