RetroSearch Browse

Fri Jul 9 20:55:03 CEST 2010 · https://mail.python.org/pipermail/python-dev/2010-July/101650.html

On Fri, Jul 9, 2010 at 06:28, Barry Warsaw <barry at python.org> wrote:
> 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.

The key point there is "autogenerated API documentation", which Python
does not do.

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

Of course.

I think this is going to be something our crazy FLUFL likes but the
kids don't. =)

-Brett

>
> -Barry
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
>
>

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://mail.python.org/pipermail/python-dev/2010-July/101650.html below:

docstring formatting in python distutils code