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. :) OTOH, the specifics don't matter as much as just picking one for the stdlib. -Barry