[SciPy-dev] Documenting function-like classes

Anne Archibald peridot.faceted@gmail....
Sun Oct 25 20:42:31 CDT 2009


2009/10/25 David Goldsmith <d.l.goldsmith@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


More information about the Scipy-dev mailing list