[commit: ghc] master: Only comments: add notes explaining the various oddities of the `Typeable` implementation for type-level literals. (2ba1a56)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2ba1a560a92f4de0938d03c48b0f2e00e382d6b6/ghc

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

commit 2ba1a560a92f4de0938d03c48b0f2e00e382d6b6
Author: Iavor S. Diatchki <diatchki at galois.com>
Date:   Wed Jun 18 10:21:06 2014 -0700

    Only comments:  add notes explaining the various oddities of the `Typeable` implementation for type-level literals.


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

2ba1a560a92f4de0938d03c48b0f2e00e382d6b6
 libraries/base/Data/Typeable/Internal.hs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/libraries/base/Data/Typeable/Internal.hs b/libraries/base/Data/Typeable/Internal.hs
index a09d4ad..4912de9 100644
--- a/libraries/base/Data/Typeable/Internal.hs
+++ b/libraries/base/Data/Typeable/Internal.hs
@@ -433,7 +433,23 @@ deriving instance Typeable Typeable
 --------------------------------------------------------------------------------
 -- Instances for type literals
 
+{- Note [Potential Collisions in `Nat` and `Symbol` instances]
+
+Kinds resulting from lifted types have finately many type-constructors.
+This is not the case for `Nat` and `Symbol`, which both contain *infinately*
+many type constructors (e.g., `Nat` has 0, 1, 2, 3, etc.).  One might think
+that this would increase the chance of hash-collisions in the type but this
+is not the case because the finger-print stored in a `TypeRep` identifies
+the whole *type* and not just the type constructor.  This is why the chance
+of collisions for `Nat` and `Symbol` is not any worse than it is for other
+lifted types with infinately many inhabitants.  Indeed, `Nat` is
+isomorphic to (lifted) `[()]`  and `Symbol` is isomprohic to `[Char]`.
+-}
+
+-- See `Note [Kinds Containing Only Literals]` in `types/Unify.hs` for
+-- an explanation of how we avoid overlap with `Typeable (f a)`.
 instance KnownNat n => Typeable (n :: Nat) where
+  -- See #9203 for an explanation of why this is written as `\_ -> rep`.
   typeRep# = \_ -> rep
     where
     rep = mkTyConApp tc []
@@ -449,7 +465,10 @@ instance KnownNat n => Typeable (n :: Nat) where
     mk a b c = a ++ " " ++ b ++ " " ++ c
 
 
+-- See `Note [Kinds Containing Only Literals]` in `types/Unify.hs` for
+-- an explanation of how we avoid overlap with `Typeable (f a)`.
 instance KnownSymbol s => Typeable (s :: Symbol) where
+  -- See #9203 for an explanation of why this is written as `\_ -> rep`.
   typeRep# = \_ -> rep
     where
     rep = mkTyConApp tc []