#14912: UniqueRepresentation tutorial could use more love
--------------------------------------------+----------------------------
Reporter: darij | Owner:
Type: defect | Status: needs_review
Priority: major | Milestone:
Component: documentation | Resolution:
Keywords: documentation, structure | Merged in:
Authors: Simon King | Reviewers:
Report Upstream: N/A | Work issues:
Branch: | Commit:
Dependencies: | Stopgaps:
--------------------------------------------+----------------------------
Old description:
> Sadly not my love, unless someone teaches me enough of the stuff that I
> understand it myself.
>
> http://www.sagemath.org/doc/reference/structure/sage/structure/unique_representation.html
>
> One thing I don't understand is:
> {{{
> the preprocessing on the arguments should be idempotent. Namely, If
> MyClass2.__classcall__ calls
> CachedRepresentation.__classcall__(<some_arguments>), then it should
> accept <some_arguments> as its own input, and pass it down unmodified to
> CachedRepresentation.__classcall__().
> }}}
> What is meant by "accept <some_arguments> as its own input"?
>
> Something that possibly should be added is some explanation of the
> difference between {{{__classcall__}}} and {{{__classcall_private__}}}.
> Maybe it doesn't belong there, but then again I have no idea where it
> belongs as it seems not documented at all...
>
> Also there seems to be a typo:
>
> {{{
> The UniqueRepresentation and UniqueFactory classes provide two
> alternative implementations of this design pattern. Both implementations
> have their own merits. UniqueRepresentation is very easy to use: a class
> just needs to derive from it, or make sure some of its super classes
> does. Also, it groups together the class and the factory in a single
> gadget; in the example above, one would want to do:
> }}}
>
> I think it's UniqueFactory, not UniqueRepresentation, which is easy to
> use etc.
New description:
Sadly not my love, unless someone teaches me enough of the stuff that I
understand it myself.
http://www.sagemath.org/doc/reference/structure/sage/structure/unique_representation.html
One thing I don't understand is:
{{{
the preprocessing on the arguments should be idempotent. Namely, If
MyClass2.__classcall__ calls
CachedRepresentation.__classcall__(<some_arguments>), then it should
accept <some_arguments> as its own input, and pass it down unmodified to
CachedRepresentation.__classcall__().
}}}
What is meant by "accept <some_arguments> as its own input"?
Something that possibly should be added is some explanation of the
difference between {{{__classcall__}}} and {{{__classcall_private__}}}.
Maybe it doesn't belong there, but then again I have no idea where it
belongs as it seems not documented at all...
Also there seems to be a typo:
{{{
The UniqueRepresentation and UniqueFactory classes provide two alternative
implementations of this design pattern. Both implementations have their
own merits. UniqueRepresentation is very easy to use: a class just needs
to derive from it, or make sure some of its super classes does. Also, it
groups together the class and the factory in a single gadget; in the
example above, one would want to do:
}}}
I think it's UniqueFactory, not UniqueRepresentation, which is easy to use
etc.
__Apply__
[attachment:trac14912-unique_doc.patch]
--
Comment (by SimonKing):
I have folded the two patches, and I have added a note on "static
methods", including a link to the Python docs.
I did not elaborate on `__new__` versus `__init__` versus `__classcall__`,
yet.
Apply trac14912-unique_doc.patch
--
Ticket URL: <http://trac.sagemath.org/ticket/14912#comment:20>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/groups/opt_out.
