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

[David Goldsmith]

Excellent, Ralf, thanks!

DG

--- On Sat, 6/20/09, Ralf Gommers <ralf.gommers@googlemail.com> wrote:

> From: Ralf Gommers <ralf.gommers@googlemail.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:46 PM
> 
> 
> On Sat, Jun 20, 2009 at 8:41 PM,
> David Goldsmith <d_l_goldsmith@yahoo.com>
> wrote:
> 
> 
> 
> 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.
> 
> 
> 
> 
> Look at ndarray for an example: http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray
> 
> Documenting the class indeed means its __init__
> function as far as Parameters, See Also, Examples, etc. This
> is what has been done so far for all classes I've looked
> at. 
> 
> 
> 
> The Methods and Attributes sections show up automatically,
> and contain all public methods/attributes, so don't
> worry about putting a list of those in. Those
> methods/attributes do have their own docstrings.
> 
> Cheers,
> 
> Ralf
> 
> 
>  
> 
> 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
> 
> >
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> 
> Scipy-dev mailing list
> 
> Scipy-dev@scipy.org
> 
> http://mail.scipy.org/mailman/listinfo/scipy-dev
> 
> 
> 
> 
> -----Inline Attachment Follows-----
> 
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>