[GHC] #8888: Document Coercible in user's guide

[GHC]

#8888: Document Coercible in user's guide
-------------------------------------+------------------------------------
        Reporter:  goldfire          |            Owner:
            Type:  bug               |           Status:  new
        Priority:  normal            |        Milestone:  7.8.1
       Component:  Documentation     |          Version:  7.8.1-rc2
      Resolution:                    |         Keywords:
Operating System:  Unknown/Multiple  |     Architecture:  Unknown/Multiple
 Type of failure:  None/Unknown      |       Difficulty:  Unknown
       Test Case:                    |       Blocked By:
        Blocking:                    |  Related Tickets:
-------------------------------------+------------------------------------

Comment (by simonpj):

 Well, there really is a new form of constraint, written `(Coercible s t)`.
 It isn't really a class constraint, although by design it behaves in
 analogous ways.  But you can't declare instances of `Coercible`, and it
 has special constraint-solving rules all of its own.  That sounds like a
 language extension to me!  There is no new syntax, but there ''is'' a new
 sort of constraint.

 I think it deserves its own section in Chapter 7.   That's where users
 will lok.

 As to "spreading the documentation around", where (apart from the paper)
 are the solving rules for `Coercible` given?  Perhaps with the (data
 type!) `Corecible` in `GHC.Types`?  I'd be happier with a reference from
 there to the user manual, I think.

 Mind you, I'm puzzled.  `Data.Coerce` in package `base` imports
 `Coercible` from `GHC.Prim` (which has no corresponding Haskell module).
 But `GHC.Types` in package `ghc-prim` defines `Coercible` (as a data
 type).  So where is it defined?  In `GHC.Prim` or `GHC.Types`?  The Name
 defined in `PrelNames` suggests the latter.

 Also oddly, `PrelNames` defines `gHC_COERCIBLE` which seems to be unused
 ... delete?

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/8888#comment:3>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler