[Doc-SIG] epydoc reST markup for stdlib docstrings
barry at python.org
Wed Apr 14 13:38:45 CEST 2010
On Apr 13, 2010, at 08:55 PM, David Goodger wrote:
>I'm not a fan of epydoc's conventions (too much like JavaDoc, too
>verbose, too strict). On the other hand, "now is better than never" --
>working code and rough consensus rule. I wouldn't object to making the
>epydoc field conventions *a* standard convention, allowing for others.
>Just as choice of markup is very much a matter of personal preference
>(some people *love* dealing with XML directly), choice of API
>documentation semantics is also a personal preference thing. We would
>be wise to allow for choice.
Perhaps it would be useful to survey some popular and/or large Python code
bases to see what is currently being used? That would be a good start to try
to figure out what the stdlib should recommend.
I do think that we should make strong recommendations for the standard
library, so that we have consistency and good online documentation. I
personally like epydoc reST format (not JavaDoc) but I'm sure there are other
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 836 bytes
Desc: not available
More information about the Doc-SIG