[SciPy-dev] Documenting function-like classes

[David Goldsmith]

On Sun, Oct 25, 2009 at 6:42 PM, Anne Archibald
<peridot.faceted at gmail.com>wrote:

> 2009/10/25 David Goldsmith <d.l.goldsmith at gmail.com>:
> > Quoting
> >
> http://docs.scipy.org/numpy/Questions+Answers/#how-to-document-the-class-numpy-ufuncs
> :
> >
> > " How to document (the class) numpy.ufuncs
> >
> > Though a class, numpy.ufuncs is presently documented, albeit not "to
> spec,"
> > as if it were a function; how should we document it?
> >
> > David Goldsmith, 2009-07-21
> >
> > I vote for as a class. As a consequence, I think, much of what's in there
> > now can/should be disposed of: it more properly belongs in the docstrings
> of
> > specific ufunc instances anyway, IMO.
> >
> > David Goldsmith, 2009-07-21
> >
> > As a function. This goes for all classes that pretend to be functions
> IMHO.
> > If a class has a __call__ method for example, it needs a Returns section.
> > Pydocweb will complain right now, but this can be fixed.
> >
> > Ralf Gommers, 2009-10-25*
> >
> > "
>
> Er, just to be clear: what you are describing is a class whose
> *instances* behave like functions, right? Because all normal classes
> behave like functions: MyClass() generates an instance of MyClass.
>
> > What *is* the design motivation behind having a function-like class
> anyway?
>
> Generally, I use one when an object I am representing with a class has
> a natural evaluation map. So, for example, an object representing a
> polynomial ought to be a class - you can multiply it, you can compute
> derivatives and antiderivatives, you can look at its coefficients -
> but you should also be able to use it like a function, to evaluate at
> a particular place.
>
> When documenting such a thing, it seems to me you should treat
> __call__ like __init__ or any other method whose name is a bit
> obscure. Which, as I understand it, means that the class docstring
> should mention the existence of them but the bulk of the documentation
> should be in the method docstring.
>
> Anne
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>

Thanks, Robert and Anne.  Would either of you care to opine: document these
as classes or as functions?  Thanks again,

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091025/67b4b0c8/attachment.html>