Comments and layout

4 files changed, 44 insertions, 21 deletions

diff --git a/compiler/basicTypes/DataCon.lhs b/compiler/basicTypes/DataCon.lhs
index c773d58a75..9bb41fcd60 100644
--- a/compiler/basicTypes/DataCon.lhs
+++ b/compiler/basicTypes/DataCon.lhs
@@ -536,7 +536,7 @@ mkDataCon name declared_infix
 	-- dictionary arguments right here.
     full_theta   = eqSpecPreds eq_spec ++ theta
     real_arg_tys = full_theta                         ++ orig_arg_tys
-    real_stricts = map mk_dict_strict_mark full_theta ++ arg_stricts
+    real_stricts = map mk_pred_strict_mark full_theta ++ arg_stricts
 
 	-- Representation arguments and demands
 	-- To do: eliminate duplication with MkId
@@ -550,12 +550,21 @@ mkDataCon name declared_infix
 eqSpecPreds :: [(TyVar,Type)] -> ThetaType
 eqSpecPreds spec = [ mkEqPred (mkTyVarTy tv, ty) | (tv,ty) <- spec ]
 
-mk_dict_strict_mark :: PredType -> HsBang
-mk_dict_strict_mark pred | isEqPred pred = HsUnpack
-			 | otherwise     = HsNoBang
-
+mk_pred_strict_mark :: PredType -> HsBang
+mk_pred_strict_mark pred 
+  | isEqPred pred = HsUnpack	-- Note [Unpack equality predicates]
+  | otherwise     = HsNoBang
 \end{code}
 
+Note [Unpack equality predicates]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If we have a GADT with a contructor C :: (a~[b]) => b -> T a
+we definitely want that equality predicate *unboxed* so that it
+takes no space at all.  This is easily done: just give it
+an UNPACK pragma. The rest of the unpack/repack code does the
+heavy lifting.  This one line makes every GADT take a word less
+space for each equality predicate, so it's pretty important!
+
 \begin{code}
 -- | The 'Name' of the 'DataCon', giving it a unique, rooted identification
 dataConName :: DataCon -> Name
@@ -659,7 +668,7 @@ dataConStrictMarks = dcStrictMarks
 -- | Strictness of evidence arguments to the wrapper function
 dataConExStricts :: DataCon -> [HsBang]
 -- Usually empty, so we don't bother to cache this
-dataConExStricts dc = map mk_dict_strict_mark (dataConTheta dc)
+dataConExStricts dc = map mk_pred_strict_mark (dataConTheta dc)
 
 -- | Source-level arity of the data constructor
 dataConSourceArity :: DataCon -> Arity
diff --git a/compiler/basicTypes/Var.lhs b/compiler/basicTypes/Var.lhs
index 3319fdfe1e..ae8bada526 100644
--- a/compiler/basicTypes/Var.lhs
+++ b/compiler/basicTypes/Var.lhs
@@ -90,22 +90,35 @@ import Data.Data
 -- large number of SOURCE imports of Id.hs :-(
 
 \begin{code}
-type EvVar = Var        -- An evidence variable: dictionary or equality constraint
-     	       		-- Could be an DictId or a CoVar
+type Id    = Var       -- A term-level identifier
+type TyVar = Var
 
-type Id     = Var       -- A term-level identifier
+-- See Note [Evidence: EvIds and CoVars]
+type EvId   = Id        -- Term-level evidence: DictId, IpId, or EqVar
+type EvVar  = EvId	-- ...historical name for EvId
 type DFunId = Id	-- A dictionary function
-type EvId   = Id        -- Term-level evidence: DictId or IpId
 type DictId = EvId	-- A dictionary variable
 type IpId   = EvId      -- A term-level implicit parameter
 type EqVar  = EvId      -- Boxed equality evidence
 
-type TyVar = Var
-type CoVar = Id		-- A coercion variable is simply an Id
-			-- variable of kind @#@. Its
-			-- 'varType' is always @ty1 ~# ty2@
+type CoVar = Id		-- See Note [Evidence: EvIds and CoVars]
 \end{code}
 
+Note [Evidence: EvIds and CoVars]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* An EvId (evidence Id) is a *boxed*, term-level evidence variable 
+  (dictionary, implicit parameter, or equality).
+
+* DictId, IpId, and EqVar are synonyms when we know what kind of
+  evidence we are talking about.  For example, an EqVar has type (t1 ~ t2).
+
+* A CoVar (coercion variable) is an *unboxed* term-level evidence variable
+  of type (t1 ~# t2).  So it's the unboxed version of an EqVar.
+
+* Only CoVars can occur in Coercions (but NB the LCoercion hack; see
+  Note [LCoercions] in Coercion).
+
+
 %************************************************************************
 %*									*
 \subsection{The main data type declarations}
diff --git a/compiler/types/Class.lhs b/compiler/types/Class.lhs
index a10b19efe7..e66d10c7e6 100644
--- a/compiler/types/Class.lhs
+++ b/compiler/types/Class.lhs
@@ -48,10 +48,14 @@ A @Class@ corresponds to a Greek kappa in the static semantics:
 \begin{code}
 data Class
   = Class {
-	classKey  :: Unique,		-- Key for fast comparison
+	classTyCon :: TyCon,		-- The data type constructor for
+					-- dictionaries of this class
+
 	className :: Name,              -- Just the cached name of the TyCon
+	classKey  :: Unique,		-- Cached unique of TyCon
 	
-	classTyVars  :: [TyVar],	-- The class type variables
+	classTyVars  :: [TyVar],	-- The class type variables;
+		     			-- identical to those of the TyCon
 	classFunDeps :: [FunDep TyVar],	-- The functional dependencies
 
 	-- Superclasses: eg: (F a ~ b, F b ~ G a, Eq a, Show b)
@@ -65,10 +69,7 @@ data Class
         classATs     :: [TyCon],	-- Associated type families
 
         -- Class operations (methods, not superclasses)
-	classOpStuff :: [ClassOpItem],	-- Ordered by tag
-
-	classTyCon :: TyCon		-- The data type constructor for
-					-- dictionaries of this class
+	classOpStuff :: [ClassOpItem]	-- Ordered by tag
      }
   deriving Typeable
 
diff --git a/compiler/types/Coercion.lhs b/compiler/types/Coercion.lhs
index b79efc5e4a..ea2edc3077 100644
--- a/compiler/types/Coercion.lhs
+++ b/compiler/types/Coercion.lhs
@@ -294,7 +294,7 @@ isCoVar :: Var -> Bool
 isCoVar v = isCoVarType (varType v)
 
 isCoVarType :: Type -> Bool
-isCoVarType ty 
+isCoVarType ty 	    -- Tests for t1 ~# t2, the unboxed equality
   | Just tc <- tyConAppTyCon_maybe ty = tc `hasKey` eqPrimTyConKey
   | otherwise                         = False
 \end{code}