<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
On 14/04/2010 13:38, Barry Warsaw wrote:
<blockquote cite="mid:20100414073845.479aa15d@heresy" type="cite">
<pre wrap="">On Apr 13, 2010, at 08:55 PM, David Goodger wrote:
</pre>
<blockquote type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<pre wrap="">
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.
</pre>
</blockquote>
<br>
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?<br>
<br>
I don't recall *ever* seeing a consistent pattern for specifying
parameters and return values in Python docstrings.<br>
<br>
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...<br>
<br>
Michael<br>
<br>
<blockquote cite="mid:20100414073845.479aa15d@heresy" type="cite">
<pre wrap="">
-Barry
</pre>
<pre wrap="">
<fieldset class="mimeAttachmentHeader"></fieldset>
_______________________________________________
Doc-SIG maillist - <a class="moz-txt-link-abbreviated" href="mailto:Doc-SIG@python.org">Doc-SIG@python.org</a>
<a class="moz-txt-link-freetext" href="http://mail.python.org/mailman/listinfo/doc-sig">http://mail.python.org/mailman/listinfo/doc-sig</a>
</pre>
</blockquote>
<br>
<br>
<pre class="moz-signature" cols="72">--
<a class="moz-txt-link-freetext" href="http://www.ironpythoninaction.com/">http://www.ironpythoninaction.com/</a></pre>
</body>
</html>