#14912: UniqueRepresentation tutorial could use more love
--------------------------------------------+------------------------------
Reporter: darij | Owner:
Type: defect | Status: needs_review
Priority: major | Milestone: sage-5.13
Component: documentation | Resolution:
Keywords: documentation, structure | Merged in:
Authors: Simon King | Reviewers: Darij Grinberg
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.
>
> Apply:
>
> * [attachment:trac14912-unique_doc.patch]
> * [attachment:trac_14912-comments-dg.patch]
> * [attachment:trac_14912-link_tweaks-ts.patch]
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]
* [attachment:trac_14912-comments-dg.patch]
* [attachment:trac_14912-more-ts-dg.patch]
--
Comment (by darij):
Oops, I've just edited Travis's patch instead of qnewing my own. So glad I
soon won't have the hg workflow anymore to trip over...
Anyway, here is my "review patch". It is not so much as a review but a
more informative documentation of what exactly to do with `UniqueFactory`.
Now, "more informative" does not necessarily mean "correct", so I'd much
prefer someone more experienced than me to look this through
(particularly, but not only, checking my interpretation of `other_keys`).
I still don't grok the note about the `__classcall__` method being static
in the unique representation doc, but I didn't really have the time to
RTFM about descriptors. If the note is clear to you, Travis, just say so
and it will plug this hole in my review.
for the '''patchbot''':
apply trac14912-unique_doc.patch trac_14912-comments-dg.patch trac_14912
-more-ts-dg.patch
--
Ticket URL: <http://trac.sagemath.org/ticket/14912#comment:30>
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.
