[SciPy-dev] Documenting function-like classes

[Anne Archibald]

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