[SciPy-dev] Documenting function-like classes

Ralf Gommers ralf.gommers@googlemail....
Mon Oct 26 04:17:25 CDT 2009


On Mon, Oct 26, 2009 at 3:20 AM, Anne Archibald
<peridot.faceted@gmail.com>wrote:

> Well, IMHO, these objects are classes, and so should be documented as
> such. The function-like documentation should be the documentation for
> __call__.
>
> That said, I haven't been working on the docstrings, so I don't know
> how people have been documenting classes; it seems to me there's
> always some question of what goes in the class docstring and what goes
> in the method docstrings. In the case of weirdly-named methods like
> __call__ and __init__, one has to be sure that the user can find them
> and knows how to call them, but that's a problem when documenting all
> classes.
>

We decided a while ago that the parameters for __init__ go in the class
docstring, not in __init__. Only public methods get substantial
documentation in their own docstrings, and get their own wiki page. __call__
should be the same as __init__ IMO. Same for __getitem__ and similar such
things. They can be clarified with examples without mentioning them by name.

See for example poly1d (__call__) or mgrid (__getitem__):
http://docs.scipy.org/numpy/docs/numpy.lib.polynomial.poly1d/
http://docs.scipy.org/numpy/docs/numpy.lib.index_tricks.mgrid/

We should not expect most users to know, or care much about, the details of
how such special (double-underscore) class methods work.

Cheers,
Ralf


> I would guess that the confusion is arising because you're looking at
> classes that don't really do much other than act like functions? Maybe
> work through something like poly1d that has substantial data and other
> methods first.
>
> Anne
>
> > DG
> >
> >
> > _______________________________________________
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091026/ceeb6b36/attachment.html 


More information about the Scipy-dev mailing list