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