[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 nomeata):

 >  I'd welcome opinions from others.

 Me too.

 Adding the cross-references you mention makes perfect sense, will do it in
 a moment.

 > So how does this even compile?

 `coercibleTyCon` is added to `ghcPrimExports` in `PrelInfo`.

 I recall that when I was exporting it from `GHC.Types`, haddock would
 display it as a regular data type, not as a constraint.

 I now added this note:

 {{{
 Note [Kind-changing of (~) and Coercible]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 (~) and Coercible are tricky to define. To the user, they must appear as
 constraints, but we cannot define them as such in Haskell. But we also
 cannot
 just define them only in GHC.Prim (like (->)), because we need a real
 module
 for them, e.g. to compile the constructor's info table.

 Furthermore the type of MkCoercible cannot be written in Haskell (no
 syntax for
 ~#R).

 So we define them as regular data types in GHC.Types, but do /not/ export
 them.
 This ensures we have a home module. We then define them with the types and
 kinds that we actually want, in TysWiredIn, and export them in GHC.Prim.

 Haddock still takes the documentation from GHC.Types (and not from the
 fake
 module created from primops.txt.pp), so we have the user-facing
 documentation
 here.
 }}}

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