The discussion was back and forth with SPJ and Richard Eisenberg during the discussion about the creation of the roles machinery and Simon suggested the shape it currently has to me last night.
Having this in the class is the only way that this can lift over an 'unknown' Functor in local scope, and permits users of a functor that is polymorphic to get access to the O(1) coercion machinery.
Without it Coercible is almost completely useless in any code that has any sort of polymorphism involved.
This is analogous to (<$), which was added to Functor explicitly because it made an asymptotic performance difference in a large number of scenarios.
The reason this has to live in the class is analogous to how Data has to hold the at-first-glance redundant dataCast1 and dataCast2, because it is the only place the right things are known, despite them always being gcast1 and gcast2. See 7.4 in
Scrap more boilerplate: reflection, zips, and generalised casts for a discussion of an almost identical issue.
There is still some work to be done here. I definitely agree that we should add some docs to it.
One of the reasons why we didn't in this initial commit is because there is some of it still up in the air in terms of what is possible. The current default definition is in terms of 'fmap coerce', so it'll currently work with even 'illegal' functors that don't have a representational argument, but the user doesn't see any improvement unless One of the reasons the docs didn't go in with the first commit was that there is room for improvement. If we can improve some things about Coercible inference we may be able to upgrade it to actually use 'coerce' via a default signature.
-Edward