On 14/04/2010 16:07, Barry Warsaw wrote:
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I
haven't looked at the Epydoc convention for parameters (etc) well enough
to have an opinion on that.
The thing I like about them is that the rules are very simple, and once
learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
Those look very clean to me, and fairly similar to what we already do in
the ReST docs.
Because epydoc works with tags rather than sections, it looks a lot
"noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical
whitespace. And I like the tags of epydoc format on the left side for their
regularity. Everyone's got a different opinion, and the only one that matters
is the BDFL's. :)
Well, perhaps move this discussion to python-dev with the intent of
creating a PEP and asking for BDFL pronouncement? The two contenders
seem to be numpy format and epydoc format. We seem to have a consensus
that adopting a standard for the standard library is a good idea.
Once we have settled on a basic format we can thrash out all the
specifics in the PEP.
All the best,
Michael
OTOH, the specifics don't matter as much as just picking one for the stdlib.
-Barry
--
http://www.ironpythoninaction.com/
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
