[Doc-SIG] epydoc reST markup for stdlib docstrings

[Michael Foord]

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 at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>    


-- 
http://www.ironpythoninaction.com/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/f620501e/attachment.html>