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
signature.asc
Description: PGP signature
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
