[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

> 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__):

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


> 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