[SciPy-dev] Documenting function-like classes
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
> 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
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.
> > DG
> > _______________________________________________
> > Scipy-dev mailing list
> > Scipyemail@example.com
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> Scipy-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev