[SciPy-dev] Documenting function-like classes

[Anne Archibald]

2009/10/25 David Goldsmith <d.l.goldsmith at gmail.com>:
> 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,

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.

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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>