On Fri, Jul 9, 2010 at 06:28, Barry Warsaw <ba...@python.org> wrote: > On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote: > >>On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou <solip...@pitrou.net> >>wrote: >>> On Wed, 7 Jul 2010 14:12:17 -0400 >>> Barry Warsaw <ba...@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@python.org > http://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > http://mail.python.org/mailman/options/python-dev/brett%40python.org > > _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
