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

 You've put a lot of work into this, and you may well be right.  I'd
 welcome opinions from others.

 For now, though, even if the main documentation stays in the library
 Haddock stuff, could you
  * add a link to the paper (which gives far more background) to the
 Haddock docs
  * add a user-manual sub-section that summarises in one paragraph and
 points off to the Haddock docs

 That way people like me who look at the manual will still end up in the
 right place.


 I'm still puzzled about two things though.
  * `Data.Coerce` has
 {{{
 import GHC.Prim (coerce, Coercible)
 }}}
  But `GHC.Prim` does not export `Coercible`.... it's defined in
 `GHC.Types`.  So how does this even compile?

  * In the
 [http://www.haskell.org/ghc/docs/7.8.1-rc2/html/libraries/base-4.7.0.0
 /Data-Coerce.html Haddock link you sent], `Coercible` shows as a class.
 But it's defined (in `GHC.Types` as a data type.  I believe that happens
 by way of `TysWiredIn.coercibleTyCon` and `coercibleClass`, but it's quite
 hard to unravel, and definitely deserves a `Note` in `GHC.Types`, and or
 `TysWiredIn` (details in one place, a pointer in the other.  It may well
 be that the way that `(~)` is handled needs similar documentation.

 Simon

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