[commit: packages/ghc-prim] master: Note [Kind-changing of (~) and Coercible] (b31737d)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc-prim

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/b31737dfe6c1d8e973b3bc94c2bcee1a74fba29f/ghc-prim

>---------------------------------------------------------------

commit b31737dfe6c1d8e973b3bc94c2bcee1a74fba29f
Author: Joachim Breitner <mail at joachim-breitner.de>
Date:   Fri Mar 14 11:28:35 2014 +0100

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


>---------------------------------------------------------------

b31737dfe6c1d8e973b3bc94c2bcee1a74fba29f
 GHC/Types.hs |   26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/GHC/Types.hs b/GHC/Types.hs
index 310c04d..25f4176 100644
--- a/GHC/Types.hs
+++ b/GHC/Types.hs
@@ -81,6 +81,28 @@ or the '>>' and '>>=' operations from the 'Monad' class.
 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
 
 
+{-
+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.
+-}
+
+
 -- | A data constructor used to box up all unlifted equalities
 --
 -- The type constructor is special in that GHC pretends that it
@@ -88,9 +110,6 @@ newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
 data (~) a b = Eq# ((~#) a b)
 
 
--- Despite this not being exported here, the documentation will
--- be used by haddock, hence the user-facing blurb here, and not in primops.txt.pp:
-
 -- | This two-parameter class has instances for types @a@ and @b@ if
 --      the compiler can infer that they have the same representation. This class
 --      does not have regular instances; instead they are created on-the-fly during
@@ -135,6 +154,7 @@ data (~) a b = Eq# ((~#) a b)
 --
 --      /Since: 4.7.0.0/
 data Coercible a b = MkCoercible ((~#) a b)
+-- Also see Note [Kind-changing of (~) and Coercible]
 
 -- | Alias for tagToEnum#. Returns True of its parameter is 1# and False
 --   if it is 0#.