Automatically move _apply() and _call() doc to __call__ about odl HOT 15 CLOSED

This is a very nice idea. I think it would go into _OperatorMeta.__new__.

Quite honestly this is also the last chance we have to somehow unify _apply and _call, it would be very much preferable imo, and would greatly simplify this.

from odl.

This is a very nice idea. I think it would go into _OperatorMeta.__new__.

Rather into _OperatorMeta.__call__. Some research necessary here.

Quite honestly this is also the last chance we have to somehow unify _apply and _call, it would be very much preferable imo, and would greatly simplify this.

I agree. So I suppose that would be a _call() method, either without out argument (old _call()) or with (an optional) out argument (old _apply()) and use inspect to check what it is.

Actually, we could get rid of the metaclass altogether by that if I remember correctly.

from odl.

We have three cases of operators

• inplace
• out of place
• inplace + out of place

This if we have a _call(x, out) for example, this does not imply the existence of a inplace operation. Some thought needed.

from odl.

These could be reflected in the arguments to _call()

• one positional argument (x) --> in-place
• two positional arguments (x, out) --> out-of-place
• two positional arguments, second optional (x, out=None) --> either way, depending on out

kwargs would be passed through from __call__().

from odl.

Nice idea, we would need to be VERY explicit about this then. Would we enforce the naming? If so preferably only on out.

from odl.

If so, definitely only on out. I'll try an implementation today so we get this done.

from odl.

And agreed, this would be super-explicit in the docstring, and we should add a section "How to implement and operator" in the online doc.

from odl.

I'll make a new issue for the _call() change.

from odl.

This is ancient, do we work on it?

from odl.

There's still an ancient branch, but I'm not so sure how to do this reliably. I started some coding and found myself writing a docstring parser. Then I realized that it was no easy fix. Maybe it's better to just always document Operator._call officially so the documentation is exposed. We could simply add a hint in Operator.__call__ so users look up at the right place in the docs.

from odl.

What happens to a See Also placed inside Operator.__call__? Ill do a test.

from odl.

Seems it links to Operator._call, damnit.

from odl.

That was my first thought, too, but having it point to the overridden _call automatically is not so easy I guess.

from odl.

Any more thoughts here? I say we close this and instead encourage users to write a short description of the operator, roughly what it does, in the class docstring. Extensive explanations in the _call docstring are of limited use anyway.

from odl.

I agree.

from odl.