Hi all!
On 6 Okt., 16:46, kcrisman <[email protected]> wrote:
> On Oct 6, 10:25 am, John Cremona <[email protected]> wrote:
>
> > On Wed, Oct 6, 2010 at 3:10 PM, David Joyner <[email protected]> wrote:
> > > This is a really excellent response!
>
> > > Do you think it should be added to the FAQ on the wiki ("I wanted to find
> > > the code for a function using
> > > sage: foo??
> > > but couldn't. What is going on here?"),
>
> > +1
+1
> Well, what should really be done is to make this sort of thing not
> happen when we do ?? Jason, is that at all technically feasible, or
> is it even more complicated than your coercion answer?
Yes, ?? should show the code. But, as far as I know, this is difficult
for special methods in Cython.
For example, if I am not mistaken, if X is an instance of a Cython
class, then X.__cmp__? (and similarly for other special methods) will
not even show you the docstring that was given to the method.
But even *if* ?? would show the source code: We must not forget that,
for example, X.__mul__ is a generic method inherited from a different
class, and there are good reasons for it (X being a ring element).
So, in these cases, showing the code would *not* show how the
functionality is ultimately implemented.
Or do you suggest that X.__mul__?? should also show the code of
X._mul_ ? I doubt that this would be feasible/reasonable.
I think
* ...? should show the documentation and ...?? show the code, even for
special methods in Cython, and also if a decorator is used; I don't
know if/how this can be achieved, though.
* If there is a generic method, like __mul__, then X.__mul__?? should
show the code of this generic method, but should not forward to the
code of a different method like X._mul_.
* The code of any generic method should provide extensive comments on
how this generic method should be implemented.
For example,
sage: RingElement.__mul__??
provides the comment
# Try fast pathway if they are both RingElements and the
parents match.
# (We know at least one of the arguments is a RingElement. So
if their
# types are *equal* (fast to check) then they are both
RingElements.
# Otherwise use the slower test via PY_TYPE_CHECK.)
That's a good thing (and better than Element.__mul__, that has no
documentation at all)!
But it could still be improved. I suggest that in addition it is
explicitly stated what a programmer should do, such as
# Multiplication of ring elements is supposed to be implemented in
a
# method called _mul_(self,other).
# That method returns the product of self and other. In that
method,
# self and other are guaranteed to belong to the same ring.
# Please do not overwrite the generic __mul__ method!
I know that this kind of information is available in some places in
the documentation. But some redundancy is helpful, IMO. Why not have
it stated in the code *and* in the docstring?
Cheers,
Simon
--
To post to this group, send an email to [email protected]
To unsubscribe from this group, send an email to
[email protected]
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
