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

[David Goldsmith]

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 at gmail.com> wrote:

> From: Pierre GM <pgmdevlist at gmail.com>
> Subject: Re: [SciPy-dev] Doc-ing classes and data attributes
> To: "SciPy Developers List" <scipy-dev at 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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>