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

 Now that we have rc builds with documentation, I can actually point you to
 the docs (we don’t have that for HEAD):

 http://www.haskell.org/ghc/docs/7.8.1-rc2/html/libraries/base-4.7.0.0
 /Data-Coerce.html

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

 I doubt that – I find my documentation via hoogle or hayoo, or via the
 package index. It would also work much better for those who use an IDE
 like leksah, who have the haddock documentation for each identifier at
 their finger tip, but possibly not the users guide.

 Also note that for example the documentation of, for example,
 `unsafeCoerce` has actually been removed from the users guide ([7ea4966]).
 Isn’t that also a language extension?

 But this is bikeshedding and I’m not insisting, so I can move the
 documentation later today.

 >  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 definition in `GHC.Types` is just so that the constructor has an info
 table and so on. I had problems using it from `GHC.Types` (with the
 overwritten id from `PrelNames`). I was following the example set by `data
 (~) a b = Eq# ((~#) a b)`, but if that is wrong I’ll happily learn what
 the right way would have been.

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

 Yes, cruft from earlier iterations. Removed.

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