On 14/04/2010 13:38, Barry Warsaw wrote:
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.
I'm not aware of other formats beyond epydoc and javadoc (I agree with
your opinion on javadoc) - oh and the .NET xml format which I strongly
recommend we steer clear of. Do you have any references?
I don't recall *ever* seeing a consistent pattern for specifying
parameters and return values in Python docstrings.
I too would prefer a consistent pattern be adopted for the Python
standard library. Good luck finding someone to go and change all the
docstrings in the standard library to use it...
Michael
-Barry
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
--
http://www.ironpythoninaction.com/
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
