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

[Ralf Gommers]

On Sat, Jun 20, 2009 at 8:41 PM, David Goldsmith <d_l_goldsmith at 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 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
> >
>
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090620/8a878b65/attachment.html>