[SciPy-dev] Doc-ing classes and data attributes

David Goldsmith d_l_goldsmith@yahoo....
Sat Jun 20 19:41:43 CDT 2009


Thanks, Pierre, this is helpful, but the given example doesn't have any of the _other_ sections Functions have, though the docstring standard says "all but Returns are relevant," so I'm left wondering where to insert the "new" sections relative to the "old."  (I know that not _all_ Function sections will always be relevant for _all_ classes, but I assume at least some of them will be relevant for some classes, but your example doesn't clarify where to put them.)  But, FWIW, thanks.

DG

--- On Sat, 6/20/09, Pierre GM <pgmdevlist@gmail.com> wrote:

> From: Pierre GM <pgmdevlist@gmail.com>
> Subject: Re: [SciPy-dev] Doc-ing classes and data attributes
> To: "SciPy Developers List" <scipy-dev@scipy.org>
> Date: Saturday, June 20, 2009, 5:06 PM
> 
> On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote:
> 
> >
> > Ok, a couple follow-up questions: where precisely
> should  
> > documentation of __init__, and the Attributes and
> Methods sections  
> > (when needed) go?  In other words,
> docstringstandard says, "Use the  
> > same sections as outlined [for Functions]," but as
> Functions don't  
> > have __init__, Attributes, or Methods, it is unclear
> where in the  
> > "above" template these new items should go.
> 
> My 2c:
> 
> * I don't document __init__, but I put a 'Parameters'
> section in the  
> docstring of the class that describes all the input
> parameters of  
> __init__
> * Methods could be described in the docstring of the class,
> under a  
> 'Methods' entry, but it might be more appropriate to
> document them  
> outside the class.
> * Same thing for Attributes: you could have a small list in
> the  
> docstring, but as soon as you start documenting an
> attribute in  
> detail, you'd better have a separate section.
> 
> Check http://pytseries.sourceforge.net/core.timeseries.html
> for an  
> example of application.
> 
> 
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
> 


      


More information about the Scipy-dev mailing list