Split the Id related functions out from Var into Id, document Var and some of Id

compiler/basicTypes/BasicTypes.lhs

@@ -30,6 +30,8 @@ module BasicTypes(
 
 	RecFlag(..), isRec, isNonRec, boolToRecFlag,
 
+	RuleName,
+
 	TopLevelFlag(..), isTopLevel, isNotTopLevel,
 
 	OverlapFlag(..), 
@@ -129,6 +131,15 @@ instance Outputable name => Outputable (IPName name) where
     ppr (IPName n) = char '?' <> ppr n -- Ordinary implicit parameters
 \end{code}
 
+%************************************************************************
+%*									*
+		Rules
+%*									*
+%************************************************************************
+
+\begin{code}
+type RuleName = FastString
+\end{code}
 
 %************************************************************************
 %*									*

compiler/basicTypes/Id.lhs

@@ -6,25 +6,25 @@
 
 \begin{code}
 module Id (
+        -- * The main types
 	Id, DictId,
 
-	-- Simple construction
-	mkGlobalId, mkLocalId, mkLocalIdWithInfo, 
-	mkSysLocal, mkUserLocal, mkVanillaGlobal,
-	mkTemplateLocals, mkTemplateLocalsNum, mkWildId, mkTemplateLocal,
-	mkWorkerId, mkExportedLocalId,
+	-- ** Simple construction
+	mkGlobalId, mkVanillaGlobal, mkVanillaGlobalWithInfo,
+	mkLocalId, mkLocalIdWithInfo,
+	mkSysLocal, mkSysLocalM, mkUserLocal, mkUserLocalM,
 
-	-- Taking an Id apart
+	-- ** Taking an Id apart
 	idName, idType, idUnique, idInfo,
 	isId, globalIdDetails, idPrimRep,
 	recordSelectorFieldLabel,
 
-	-- Modifying an Id
+	-- ** Modifying an Id
 	setIdName, setIdUnique, Id.setIdType, setIdExported, setIdNotExported, 
-	setIdInfo, lazySetIdInfo, modifyIdInfo, maybeModifyIdInfo,
+	globaliseId, setIdInfo, lazySetIdInfo, modifyIdInfo, maybeModifyIdInfo,
 	zapLamIdInfo, zapDemandIdInfo, zapFragileIdInfo, transferPolyIdInfo,
 
-	-- Predicates
+	-- ** Predicates on Ids
 	isImplicitId, isDeadBinder, isDictId, isStrictId,
 	isExportedId, isLocalId, isGlobalId,
 	isRecordSelector, isNaughtyRecordSelector,
@@ -36,15 +36,15 @@ module Id (
         isTickBoxOp, isTickBoxOp_maybe,
 	hasNoBinding, 
 
-	-- Inline pragma stuff
+	-- ** Inline pragma stuff
 	idInlinePragma, setInlinePragma, modifyInlinePragma, 
 
 
-	-- One shot lambda stuff
+	-- ** One shot lambda stuff
 	isOneShotBndr, isOneShotLambda, isStateHackType,
 	setOneShotLambda, clearOneShotLambda,
 
-	-- IdInfo stuff
+	-- ** IdInfo stuff
 	setIdUnfolding,
 	setIdArity,
 	setIdNewDemandInfo, 
@@ -54,6 +54,7 @@ module Id (
 	setIdCafInfo,
 	setIdOccInfo,
 
+	-- ** Id demand information
 #ifdef OLD_STRICTNESS
 	idDemandInfo, 
 	idStrictness, 
@@ -81,15 +82,16 @@ module Id (
 
 #include "HsVersions.h"
 
-import CoreSyn
+import {-# SOURCE #-} CoreSyn ( CoreRule, Unfolding )
+
+import IdInfo
 import BasicTypes
 import qualified Var
-import Var hiding (mkLocalId, mkGlobalId, mkExportedLocalId)
+import Var
 import TyCon
 import Type
 import TcType
-import TysPrim
-import IdInfo 
+import TysPrim 
 #ifdef OLD_STRICTNESS
 import qualified Demand
 #endif
@@ -105,6 +107,7 @@ import Maybes
 import SrcLoc
 import Outputable
 import Unique
+import UniqSupply
 import FastString
 import StaticFlags
 
@@ -123,8 +126,58 @@ infixl 	1 `setIdUnfolding`,
 	  ,`setIdDemandInfo`
 #endif
 \end{code}
+%************************************************************************
+%*									*
+\subsection{Basic Id manipulation}
+%*									*
+%************************************************************************
+
+\begin{code}
+idName   :: Id -> Name
+idName    = Var.varName
+
+idUnique :: Id -> Unique
+idUnique  = varUnique
+
+idType   :: Id -> Kind
+idType    = varType
+
+setIdUnique :: Id -> Unique -> Id
+setIdUnique = setVarUnique
+
+setIdName :: Id -> Name -> Id
+setIdName = setVarName
+
+setIdType :: Id -> Type -> Id
+setIdType id ty = seqType ty `seq` Var.setVarType id ty
 
+setIdExported :: Id -> Id
+setIdExported = setIdVarExported
 
+setIdNotExported :: Id -> Id
+setIdNotExported = setIdVarNotExported
+
+globaliseId :: GlobalIdDetails -> Id -> Id
+globaliseId = globaliseIdVar
+
+idInfo :: Id -> IdInfo
+idInfo = varIdInfo
+
+lazySetIdInfo :: Id -> IdInfo -> Id
+lazySetIdInfo = lazySetVarIdInfo
+
+setIdInfo :: Id -> IdInfo -> Id
+setIdInfo id info = seqIdInfo info `seq` (lazySetIdInfo id info)
+        -- Try to avoid spack leaks by seq'ing
+
+modifyIdInfo :: (IdInfo -> IdInfo) -> Id -> Id
+modifyIdInfo fn id = setIdInfo id (fn (idInfo id))
+
+-- maybeModifyIdInfo tries to avoid unnecesary thrashing
+maybeModifyIdInfo :: Maybe IdInfo -> Id -> Id
+maybeModifyIdInfo (Just new_info) id = lazySetIdInfo id new_info
+maybeModifyIdInfo Nothing	  id = id
+\end{code}
 
 %************************************************************************
 %*									*
@@ -147,33 +200,44 @@ substitution (which changes the free type variables) is more common.
 Anyway, we removed it in March 2008.
 
 \begin{code}
-mkLocalIdWithInfo :: Name -> Type -> IdInfo -> Id
-mkLocalIdWithInfo name ty info = Var.mkLocalId name ty info
-	-- Note [Free type variables]
+-- | Create a global Id. Global identifiers are those that are imported or are data constructors/destructors.
+mkGlobalId :: GlobalIdDetails -> Name -> Type -> IdInfo -> Id
+mkGlobalId = mkGlobalIdVar
 
-mkExportedLocalId :: Name -> Type -> Id
-mkExportedLocalId name ty = Var.mkExportedLocalId name ty vanillaIdInfo
-	-- Note [Free type variables]
+mkVanillaGlobal :: Name -> Type -> Id
+mkVanillaGlobal name ty = mkVanillaGlobalWithInfo name ty vanillaIdInfo
 
-mkGlobalId :: GlobalIdDetails -> Name -> Type -> IdInfo -> Id
-mkGlobalId details name ty info = Var.mkGlobalId details name ty info
-\end{code}
+mkVanillaGlobalWithInfo :: Name -> Type -> IdInfo -> Id
+mkVanillaGlobalWithInfo = mkGlobalId VanillaGlobal
 
-\begin{code}
+
+-- | Create a local Id. Local identifiers are those bound at the top level of the current module or in an expression.
 mkLocalId :: Name -> Type -> Id
 mkLocalId name ty = mkLocalIdWithInfo name ty vanillaIdInfo
 
--- SysLocal: for an Id being created by the compiler out of thin air...
+mkLocalIdWithInfo :: Name -> Type -> IdInfo -> Id
+mkLocalIdWithInfo = mkLocalIdVar
+
+-- | Create a local Id that is marked as exported. This prevents things attached to it from being removed as dead code.
+mkExportedLocalId :: Name -> Type -> Id
+mkExportedLocalId name ty = mkExportedLocalIdVar name ty vanillaIdInfo
+	-- Note [Free type variables]
+
+
+-- | Create a system local Id. These are local Ids that are created by the compiler out of thin air
 mkSysLocal :: FastString -> Unique -> Type -> Id
 mkSysLocal fs uniq ty = mkLocalId (mkSystemVarName uniq fs) ty
 
+mkSysLocalM :: MonadUnique m => FastString -> Type -> m Id
+mkSysLocalM fs ty = getUniqueM >>= (\uniq -> return (mkSysLocal fs uniq ty))
+
 
--- UserLocal: an Id with a name the user might recognize...
+-- | Create a user local Id. These are local Id with a name and location that the user might recognize
 mkUserLocal :: OccName -> Unique -> Type -> SrcSpan -> Id
-mkVanillaGlobal :: Name -> Type -> IdInfo -> Id
+mkUserLocal occ uniq ty loc = mkLocalId (mkInternalName uniq occ loc) ty
 
-mkUserLocal occ uniq ty loc = mkLocalId (mkInternalName    uniq occ loc) ty
-mkVanillaGlobal 	    = mkGlobalId VanillaGlobal
+mkUserLocalM :: MonadUnique m => OccName -> Type -> SrcSpan -> m Id
+mkUserLocalM occ ty loc = getUniqueM >>= (\uniq -> return (mkUserLocal occ uniq ty loc))
 \end{code}
 
 Make some local @Ids@ for a template @CoreExpr@.  These have bogus
@@ -181,27 +245,29 @@ Make some local @Ids@ for a template @CoreExpr@.  These have bogus
 instantiated before use.
  
 \begin{code}
--- "Wild Id" typically used when you need a binder that you don't expect to use
+-- | Make a "wild Id". This is typically used when you need a binder that you don't expect to use
 mkWildId :: Type -> Id
 mkWildId ty = mkSysLocal (fsLit "wild") (mkBuiltinUnique 1) ty
 
 mkWorkerId :: Unique -> Id -> Type -> Id
--- A worker gets a local name.  CoreTidy will externalise it if necessary.
+-- | Workers get local names. CoreTidy will externalise these if necessary
 mkWorkerId uniq unwrkr ty
   = mkLocalId wkr_name ty
   where
     wkr_name = mkInternalName uniq (mkWorkerOcc (getOccName unwrkr)) (getSrcSpan unwrkr)
 
--- "Template locals" typically used in unfoldings
+-- | Create a "template local": a family of system local Ids in bijection with Ints, typically used in unfoldings
+mkTemplateLocal :: Int -> Type -> Id
+mkTemplateLocal i ty = mkSysLocal (fsLit "tpl") (mkBuiltinUnique i) ty
+
+-- | Create a template local for a series of types
 mkTemplateLocals :: [Type] -> [Id]
-mkTemplateLocals tys = zipWith mkTemplateLocal [1..] tys
+mkTemplateLocals = mkTemplateLocalsNum 1
 
+-- | Create a template local for a series of type, but start from a specified template local
 mkTemplateLocalsNum :: Int -> [Type] -> [Id]
 -- The Int gives the starting point for unique allocation
 mkTemplateLocalsNum n tys = zipWith mkTemplateLocal [n..] tys
-
-mkTemplateLocal :: Int -> Type -> Id
-mkTemplateLocal i ty = mkSysLocal (fsLit "tpl") (mkBuiltinUnique i) ty
 \end{code}
 
 
@@ -212,12 +278,23 @@ mkTemplateLocal i ty = mkSysLocal (fsLit "tpl") (mkBuiltinUnique i) ty
 %************************************************************************
 
 \begin{code}
-setIdType :: Id -> Type -> Id
-	-- Add free tyvar info to the type
-setIdType id ty = seqType ty `seq` Var.setIdType id ty
-
 idPrimRep :: Id -> PrimRep
 idPrimRep id = typePrimRep (idType id)
+
+globalIdDetails :: Id -> GlobalIdDetails
+globalIdDetails = globalIdVarDetails
+
+isId :: Id -> Bool
+isId = isIdVar
+
+isLocalId :: Id -> Bool
+isLocalId = isLocalIdVar
+
+isGlobalId :: Id -> Bool
+isGlobalId = isGlobalIdVar
+
+isExportedId :: Var -> Bool
+isExportedId = isExportedIdVar
 \end{code}
 
 
@@ -234,17 +311,16 @@ recordSelectorFieldLabel id
         RecordSelId { sel_tycon = tycon, sel_label = lbl } -> (tycon,lbl)
         _ -> panic "recordSelectorFieldLabel"
 
-isRecordSelector        :: Var -> Bool
-isNaughtyRecordSelector :: Var -> Bool
-isPrimOpId              :: Var -> Bool
-isFCallId               :: Var -> Bool
-isDataConWorkId         :: Var -> Bool
-hasNoBinding            :: Var -> Bool
+isRecordSelector        :: Id -> Bool
+isNaughtyRecordSelector :: Id -> Bool
+isPrimOpId              :: Id -> Bool
+isFCallId               :: Id -> Bool
+isDataConWorkId         :: Id -> Bool
 
-isClassOpId_maybe       :: Var -> Maybe Class
-isPrimOpId_maybe        :: Var -> Maybe PrimOp
-isFCallId_maybe         :: Var -> Maybe ForeignCall
-isDataConWorkId_maybe   :: Var -> Maybe DataCon
+isClassOpId_maybe       :: Id -> Maybe Class
+isPrimOpId_maybe        :: Id -> Maybe PrimOp
+isFCallId_maybe         :: Id -> Maybe ForeignCall
+isDataConWorkId_maybe   :: Id -> Maybe DataCon
 
 isRecordSelector id = case globalIdDetails id of
                         RecordSelId {}  -> True
@@ -289,20 +365,20 @@ isDataConId_maybe id = case globalIdDetails id of
                          _                 -> Nothing
 
 idDataCon :: Id -> DataCon
--- Get from either the worker or the wrapper to the DataCon
--- Currently used only in the desugarer
---	 INVARIANT: idDataCon (dataConWrapId d) = d
+-- ^ Get from either the worker or the wrapper to the DataCon.
+-- Currently used only in the desugarer.
+--
+--	 INVARIANT: @idDataCon (dataConWrapId d) = d@
+--
 -- (Remember, dataConWrapId can return either the wrapper or the worker.)
-idDataCon id = case globalIdDetails id of
-                  DataConWorkId con -> con
-                  DataConWrapId con -> con
-                  _                 -> pprPanic "idDataCon" (ppr id)
+idDataCon id = isDataConId_maybe id `orElse` pprPanic "idDataCon" (ppr id
 
 
 isDictId :: Id -> Bool
 isDictId id = isDictTy (idType id)
 
--- hasNoBinding returns True of an Id which may not have a
+hasNoBinding :: Id -> Bool
+-- ^ Returns True of an Id which may not have a
 -- binding, even though it is defined in this module.  
 -- Data constructor workers used to be things of this kind, but
 -- they aren't any more.  Instead, we inject a binding for 
@@ -315,9 +391,9 @@ hasNoBinding id = case globalIdDetails id of
 			_                -> False
 
 isImplicitId :: Id -> Bool
-	-- isImplicitId tells whether an Id's info is implied by other
-	-- declarations, so we don't need to put its signature in an interface
-	-- file, even if it's mentioned in some other interface unfolding.
+-- ^ isImplicitId tells whether an Id's info is implied by other
+-- declarations, so we don't need to put its signature in an interface
+-- file, even if it's mentioned in some other interface unfolding.
 isImplicitId id
   = case globalIdDetails id of
 	RecordSelId {}  -> True
@@ -396,7 +472,7 @@ setIdStrictness :: Id -> StrictnessInfo -> Id
 setIdStrictness id strict_info = modifyIdInfo (`setStrictnessInfo` strict_info) id
 #endif
 
--- isBottomingId returns true if an application to n args would diverge
+-- | Returns true if an application to n args would diverge
 isBottomingId :: Id -> Bool
 isBottomingId id = isBottomingSig (idNewStrictness id)
 
@@ -411,15 +487,13 @@ setIdNewStrictness id sig = modifyIdInfo (`setNewStrictnessInfo` Just sig) id
 
 zapIdNewStrictness :: Id -> Id
 zapIdNewStrictness id = modifyIdInfo (`setNewStrictnessInfo` Nothing) id
-\end{code}
 
-This predicate says whether the id has a strict demand placed on it or
-has a type such that it can always be evaluated strictly (e.g., an
-unlifted type, but see the comment for isStrictType).  We need to
-check separately whether <id> has a so-called "strict type" because if
-the demand for <id> hasn't been computed yet but <id> has a strict
-type, we still want (isStrictId <id>) to be True.
-\begin{code}
+-- | This predicate says whether the id has a strict demand placed on it or
+-- has a type such that it can always be evaluated strictly (e.g., an
+-- unlifted type, but see the comment for 'isStrictType').  We need to
+-- check separately whether <id> has a so-called "strict type" because if
+-- the demand for <id> hasn't been computed yet but <id> has a strict
+-- type, we still want @isStrictId <id>@ to be True.
 isStrictId :: Id -> Bool
 isStrictId id
   = ASSERT2( isId id, text "isStrictId: not an id: " <+> ppr id )

compiler/basicTypes/IdInfo.lhs

@@ -77,7 +77,6 @@ module IdInfo (
         TickBoxOp(..), TickBoxId,
     ) where
 
-import CoreSyn
 import Class
 import PrimOp
 import Name
@@ -503,9 +502,7 @@ specInfoRules (SpecInfo rules _) = rules
 
 setSpecInfoHead :: Name -> SpecInfo -> SpecInfo
 setSpecInfoHead fn (SpecInfo rules fvs)
-  = SpecInfo (map set_head rules) fvs
-  where
-    set_head rule = rule { ru_fn = fn }
+  = SpecInfo (map (setRuleIdName fn) rules) fvs
 
 seqSpecInfo :: SpecInfo -> ()
 seqSpecInfo (SpecInfo rules fvs) = seqRules rules `seq` seqVarSet fvs
@@ -747,7 +744,7 @@ zapFragileInfo :: IdInfo -> Maybe IdInfo
 zapFragileInfo info 
   = Just (info `setSpecInfo` emptySpecInfo
 	       `setWorkerInfo` NoWorker
-               `setUnfoldingInfo` NoUnfolding
+               `setUnfoldingInfo` noUnfolding
 	       `setOccInfo` if isFragileOcc occ then NoOccInfo else occ)
   where
     occ = occInfo info

compiler/basicTypes/MkId.lhs

@@ -1314,7 +1314,7 @@ errorTy  = mkSigmaTy [openAlphaTyVar] [] (mkFunTys [mkListTy charTy] openAlphaTy
 \begin{code}
 pcMiscPrelId :: Name -> Type -> IdInfo -> Id
 pcMiscPrelId name ty info
-  = mkVanillaGlobal name ty info
+  = mkVanillaGlobalWithInfo name ty info
     -- We lie and say the thing is imported; otherwise, we get into
     -- a mess with dependency analysis; e.g., core2stg may heave in
     -- random calls to GHCbase.unpackPS__.  If GHCbase is the module

compiler/basicTypes/Var.lhs

@@ -5,33 +5,72 @@
 \section{@Vars@: Variables}
 
 \begin{code}
+-- |
+-- #name_types#
+-- GHC uses several kinds of name internally:
+--
+-- * 'OccName.OccName': see "OccName#name_types"
+--
+-- * 'RdrName.RdrName': see "RdrName#name_types"
+--
+-- * 'Name.Name': see "Name#name_types"
+--
+-- * 'Id.Id': see "Id#name_types"
+--
+-- * 'Var.Var' is a synonym for the 'Id.Id' type but it may additionally potentially contain type variables, 
+--   which have a 'TypeRep.Kind' rather than a 'TypeRep.Type' and only contain some extra details during typechecking.
+--   These 'Var.Var' names may either be global or local, see "Var#globalvslocal"
+--
+-- #globalvslocal#
+-- Global 'Id's and 'Var's are those that are imported or correspond to a data constructor, primitive operation, or record selectors.
+-- Local 'Id's and 'Var's are those bound within an expression (e.g. by a lambda) or at the top level of the module being compiled.
 module Var (
-	Var, 
-	varName, varUnique, varType,
-	setVarName, setVarUnique, 
+        -- * The main data type
+	Var,
 
-	-- TyVars
-	TyVar, mkTyVar, mkTcTyVar, mkWildCoVar,
-	tyVarName, tyVarKind,
+	-- ** Constructing 'Var's
+	mkLocalIdVar, mkExportedLocalIdVar, mkGlobalIdVar, 
+
+	-- ** Taking 'Var's apart
+	varName, varUnique, varType, varIdInfo, globalIdVarDetails,
+
+	-- ** Modifying 'Var's
+	setVarName, setVarUnique, setVarType,
+	setIdVarExported, setIdVarNotExported, 
+	globaliseIdVar, lazySetVarIdInfo,
+
+        -- ** Predicates
+        isCoVar, isIdVar, isTyVar, isTcTyVar,
+        isLocalVar, isLocalIdVar,
+	isGlobalIdVar, isExportedIdVar,
+	mustHaveLocalBinding,
+
+	-- * Type variable data type
+	TyVar,
+
+	-- ** Constructing 'TyVar's
+	mkTyVar, mkTcTyVar, mkWildCoVar,
+
+	-- ** Taking 'TyVar's apart
+	tyVarName, tyVarKind, tcTyVarDetails,
+
+	-- ** Modifying 'TyVar's
 	setTyVarName, setTyVarUnique, setTyVarKind,
-	tcTyVarDetails,
 
-        -- CoVars
-        CoVar, coVarName, setCoVarUnique, setCoVarName, mkCoVar, isCoVar,
+        -- * Coercion variable data type
+        CoVar,
 
-	-- Ids
-	Id, DictId,
-	idName, idType, idUnique, idInfo, modifyIdInfo, maybeModifyIdInfo,
-	setIdName, setIdUnique, setIdType, setIdInfo, lazySetIdInfo, 
-	setIdExported, setIdNotExported,
+        -- ** Constructing 'CoVar's
+        mkCoVar,
 
-	globalIdDetails, globaliseId, 
+        -- ** Taking 'CoVar's apart
+        coVarName,
 
-	mkLocalId, mkExportedLocalId, mkGlobalId, 
+        -- ** Modifying 'CoVar's
+        setCoVarUnique, setCoVarName,
 
-	isTyVar, isTcTyVar, isId, isLocalVar, isLocalId,
-	isGlobalId, isExportedId, 
-	mustHaveLocalBinding
+	-- * 'Var' type synonyms
+	Id, DictId
     ) where
 
 #include "HsVersions.h"
@@ -39,14 +78,14 @@ module Var (
 import {-# SOURCE #-}	TypeRep( Type, Kind )
 import {-# SOURCE #-}	TcType( TcTyVarDetails, pprTcTyVarDetails )
 import {-# SOURCE #-}	IdInfo( GlobalIdDetails, notGlobalId, 
-                                IdInfo, seqIdInfo )
+                                IdInfo )
 import {-# SOURCE #-}	TypeRep( isCoercionKind )
 
 import Name hiding (varName)
 import Unique
 import FastTypes
 import FastString
-import Outputable       
+import Outputable
 \end{code}
 
 
@@ -63,13 +102,15 @@ strictness).  The essential info about different kinds of @Vars@ is
 in its @VarDetails@.
 
 \begin{code}
+-- | Essentially a typed 'Name', that may also contain some additional information
+-- about the 'Var' and it's use sites.
 data Var
   = TyVar {
 	varName    :: !Name,
 	realUnique :: FastInt,		-- Key for fast comparison
 					-- Identical to the Unique in the name,
 					-- cached here for speed
-	varType       :: Kind,
+	varType       :: Kind,          -- ^ The type or kind of the 'Var' in question
         isCoercionVar :: Bool
  }
 
@@ -98,10 +139,8 @@ data Var
 	lclDetails :: LocalIdDetails }
 
 data LocalIdDetails 
-  = NotExported	-- Not exported
-  | Exported	-- Exported
-  -- Exported Ids are kept alive; 
-  -- NotExported things may be discarded as dead code.
+  = NotExported	-- ^ Not exported: may be discarded as dead code.
+  | Exported	-- ^ Exported: kept alive
 \end{code}
 
 Note [GlobalId/LocalId]
@@ -120,7 +159,6 @@ A LocalId is
   * always treated as a candidate by the free-variable finder
 
 After CoreTidy, top-level LocalIds are turned into GlobalIds
- 
 
 \begin{code}
 instance Outputable Var where
@@ -166,6 +204,36 @@ setVarName :: Var -> Name -> Var
 setVarName var new_name
   = var { realUnique = getKeyFastInt (getUnique new_name), 
    	  varName = new_name }
+
+setVarType :: Id -> Type -> Id
+setVarType id ty = id { varType = ty }
+
+setIdVarExported :: Var -> Var
+-- ^ Exports the given local 'Id'. Can also be called on global 'Id's, such as data constructors
+-- and class operations, which are born as global 'Id's and automatically exported
+setIdVarExported id@(LocalId {}) = id { lclDetails = Exported }
+setIdVarExported other_id	      = ASSERT( isIdVar other_id ) other_id
+
+setIdVarNotExported :: Id -> Id
+-- ^ We can only do this to LocalIds
+setIdVarNotExported id = ASSERT( isLocalIdVar id ) id { lclDetails = NotExported }
+
+globaliseIdVar :: GlobalIdDetails -> Var -> Var
+-- ^ If it's a local, make it global
+globaliseIdVar details id = GlobalId { varName    = varName id,
+				    realUnique = realUnique id,
+			   	    varType    = varType id,
+				    idInfo_    = varIdInfo id,
+				    gblDetails = details }
+
+-- | Extract 'Id' information from the 'Var' if it represents a global or local 'Id', otherwise panic
+varIdInfo :: Var -> IdInfo
+varIdInfo (GlobalId {idInfo_ = info}) = info
+varIdInfo (LocalId  {idInfo_ = info}) = info
+varIdInfo other_var		   = pprPanic "idInfo" (ppr other_var)
+
+lazySetVarIdInfo :: Var -> IdInfo -> Var
+lazySetVarIdInfo id info = id { idInfo_ = info }
 \end{code}
 
 
@@ -221,8 +289,9 @@ mkTcTyVar name kind details
 %************************************************************************
 
 \begin{code}
-type CoVar = Var	-- A coercion variable is simply a type 
-			-- variable of kind (ty1 :=: ty2)
+type CoVar = Var	-- ^ A coercion variable is simply a type 
+			-- variable of kind @ty1 :=: ty2@. Hence its
+			-- 'varType' is always @PredTy (EqPred t1 t2)@
 
 coVarName :: CoVar -> Name
 coVarName = varName
@@ -237,14 +306,12 @@ mkCoVar :: Name -> Kind -> CoVar
 mkCoVar name kind = ASSERT( isCoercionKind kind )
 		    TyVar { varName    	  = name
 			  , realUnique 	  = getKeyFastInt (nameUnique name)
-			  , varType    	  = kind	
-				-- varType is always PredTy (EqPred t1 t2)
+			  , varType    	  = kind
                           , isCoercionVar = True
 			}
 
 mkWildCoVar :: Kind -> TyVar
--- A type variable that is never referred to,
--- so its unique doesn't matter
+-- ^ Create a type variable that is never referred to, so its unique doesn't matter
 mkWildCoVar kind 
   = ASSERT( isCoercionKind kind )
     TyVar { varName = mkSysTvName wild_uniq (fsLit "co_wild"),
@@ -253,164 +320,112 @@ mkWildCoVar kind
             isCoercionVar = True }
   where
     wild_uniq = mkBuiltinUnique 1
+
 \end{code}
 
 %************************************************************************
 %*									*
-\subsection{Id Construction}
+\subsection{Ids}
 %*									*
 %************************************************************************