Expanded abbreviations in Haddock documentation

This adds notes to the Haddock documentation for various core datatypes
expanding abbreviations.

Reviewers: bgamari, thomie

Differential Revision: https://phabricator.haskell.org/D2406

GHC Trac Issues: #12405

compiler/basicTypes/BasicTypes.hs

@@ -115,7 +115,9 @@ import Data.Function (on)
 -- See also Note [Definition of arity] in CoreArity
 type Arity = Int
 
--- | The number of represented arguments that can be applied to a value before it does
+-- | Representation Arity
+--
+-- The number of represented arguments that can be applied to a value before it does
 -- "real work". So:
 --  fib 100                    has representation arity 0
 --  \x -> fib x                has representation arity 1
@@ -130,8 +132,10 @@ type RepArity = Int
 ************************************************************************
 -}
 
--- | Type of the tags associated with each constructor possibility
---   or superclass selector
+-- | Constructor Tag
+--
+-- Type of the tags associated with each constructor possibility or superclass
+-- selector
 type ConTag = Int
 
 -- | A *zero-indexed* constructor tag
@@ -271,7 +275,7 @@ initialVersion = 1
 ************************************************************************
 -}
 
--- |A String Literal in the source, including its original raw format for use by
+-- | A String Literal in the source, including its original raw format for use by
 -- source to source manipulation tools.
 data StringLiteral = StringLiteral
                        { sl_st :: SourceText, -- literal raw source.
@@ -282,6 +286,8 @@ data StringLiteral = StringLiteral
 instance Eq StringLiteral where
   (StringLiteral _ a) == (StringLiteral _ b) = a == b
 
+-- | Warning Text
+--
 -- reason/explanation from a WARNING or DEPRECATED pragma
 data WarningTxt = WarningTxt (Located SourceText)
                              [Located StringLiteral]
@@ -429,6 +435,7 @@ instance Outputable Boxity where
 ************************************************************************
 -}
 
+-- | Recursivity Flag
 data RecFlag = Recursive
              | NonRecursive
              deriving( Eq, Data )
@@ -666,6 +673,7 @@ Tring is the 'representation' type.  (This just helps us remember
 whether to use 'from' or 'to'.
 -}
 
+-- | Embedding Projection pair
 data EP a = EP { fromEP :: a,   -- :: T -> Tring
                  toEP   :: a }  -- :: Tring -> T
 
@@ -692,7 +700,7 @@ the base of the module hierarchy.  So it seemed simpler to put the
 defn of OccInfo here, safely at the bottom
 -}
 
--- | Identifier occurrence information
+-- | identifier Occurrence Information
 data OccInfo
   = NoOccInfo           -- ^ There are many occurrences, or unknown occurrences
 
@@ -733,11 +741,13 @@ seqOccInfo :: OccInfo -> ()
 seqOccInfo occ = occ `seq` ()
 
 -----------------
+-- | Interesting Context
 type InterestingCxt = Bool      -- True <=> Function: is applied
                                 --          Data value: scrutinised by a case with
                                 --                      at least one non-DEFAULT branch
 
 -----------------
+-- | Inside Lambda
 type InsideLam = Bool   -- True <=> Occurs inside a non-linear lambda
                         -- Substituting a redex for this occurrence is
                         -- dangerous because it might duplicate work.
@@ -804,6 +814,7 @@ interface files; it is converted to Class.DefMethInfo before begin put in a
 Class object.
 -}
 
+-- | Default Method Specification
 data DefMethSpec ty
   = VanillaDM     -- Default method given with polymorphic code
   | GenericDM ty  -- Default method given with code of this type
@@ -911,6 +922,7 @@ type SourceText = String -- Note [Literal source text],[Pragma source text]
 When a rule or inlining is active
 -}
 
+-- | Phase Number
 type PhaseNum = Int  -- Compilation phase
                      -- Phases decrease towards zero
                      -- Zero is the last phase
@@ -933,6 +945,7 @@ data Activation = NeverActive
                 deriving( Eq, Data )
                   -- Eq used in comparing rules in HsDecls
 
+-- | Rule Match Information
 data RuleMatchInfo = ConLike                    -- See Note [CONLIKE pragma]
                    | FunLike
                    deriving( Eq, Data, Show )
@@ -955,6 +968,7 @@ data InlinePragma            -- Note [InlinePragma]
       , inl_rule   :: RuleMatchInfo  -- Should the function be treated like a constructor?
     } deriving( Eq, Data )
 
+-- | Inline Specification
 data InlineSpec   -- What the user's INLINE pragma looked like
   = Inline
   | Inlinable
@@ -1172,6 +1186,8 @@ isEarlyActive AlwaysActive      = True
 isEarlyActive (ActiveBefore {}) = True
 isEarlyActive _                 = False
 
+-- | Fractional Literal
+--
 -- Used (instead of Rational) to represent exactly the floating point literal that we
 -- encountered in the user's source program. This allows us to pretty-print exactly what
 -- the user wrote, which is important e.g. for floating point numbers that can't represented

compiler/basicTypes/DataCon.hs

@@ -437,6 +437,7 @@ but dcRepArity does.  For example:
     dcRepArity    = 2
 -}
 
+-- | Data Constructor Representation
 data DataConRep
   = NoDataConRep              -- No wrapper
 
@@ -484,20 +485,24 @@ data DataConRep
 
 -------------------------
 
--- | Bangs on data constructor arguments as the user wrote them in the
+-- | Haskell Source Bang
+--
+-- Bangs on data constructor arguments as the user wrote them in the
 -- source code.
 --
--- (HsSrcBang _ SrcUnpack SrcLazy) and
--- (HsSrcBang _ SrcUnpack NoSrcStrict) (without StrictData) makes no sense, we
+-- @(HsSrcBang _ SrcUnpack SrcLazy)@ and
+-- @(HsSrcBang _ SrcUnpack NoSrcStrict)@ (without StrictData) makes no sense, we
 -- emit a warning (in checkValidDataCon) and treat it like
--- (HsSrcBang _ NoSrcUnpack SrcLazy)
+-- @(HsSrcBang _ NoSrcUnpack SrcLazy)@
 data HsSrcBang =
   HsSrcBang (Maybe SourceText) -- Note [Pragma source text] in BasicTypes
             SrcUnpackedness
             SrcStrictness
   deriving Data.Data
 
--- | Bangs of data constructor arguments as generated by the compiler
+-- | Haskell Implementation Bang
+--
+-- Bangs of data constructor arguments as generated by the compiler
 -- after consulting HsSrcBang, flags, etc.
 data HsImplBang
   = HsLazy  -- ^ Lazy field
@@ -507,13 +512,17 @@ data HsImplBang
     -- co :: arg-ty ~ product-ty HsBang
   deriving Data.Data
 
--- | What strictness annotation the user wrote
+-- | Source Strictness
+--
+-- What strictness annotation the user wrote
 data SrcStrictness = SrcLazy -- ^ Lazy, ie '~'
                    | SrcStrict -- ^ Strict, ie '!'
                    | NoSrcStrict -- ^ no strictness annotation
      deriving (Eq, Data.Data)
 
--- | What unpackedness the user requested
+-- | Source Unpackedness
+--
+-- What unpackedness the user requested
 data SrcUnpackedness = SrcUnpack -- ^ {-# UNPACK #-} specified
                      | SrcNoUnpack -- ^ {-# NOUNPACK #-} specified
                      | NoSrcUnpack -- ^ no unpack pragma

compiler/basicTypes/IdInfo.hs

@@ -102,7 +102,9 @@ infixl  1 `setRuleInfo`,
 ************************************************************************
 -}
 
--- | The 'IdDetails' of an 'Id' give stable, and necessary,
+-- | Identifier Details
+--
+-- The 'IdDetails' of an 'Id' give stable, and necessary,
 -- information about the Id.
 data IdDetails
   = VanillaId
@@ -138,6 +140,7 @@ data IdDetails
                -- This only covers /un-lifted/ coercions, of type
                -- (t1 ~# t2) or (t1 ~R# t2), not their lifted variants
 
+-- | Recursive Selector Parent
 data RecSelParent = RecSelData TyCon | RecSelPatSyn PatSyn deriving Eq
   -- Either `TyCon` or `PatSyn` depending
   -- on the origin of the record selector.
@@ -187,7 +190,9 @@ pprIdDetails other     = brackets (pp other)
 ************************************************************************
 -}
 
--- | An 'IdInfo' gives /optional/ information about an 'Id'.  If
+-- | Identifier Information
+--
+-- An 'IdInfo' gives /optional/ information about an 'Id'.  If
 -- present it never lies, but it may not be present, in which case there
 -- is always a conservative assumption which can be made.
 --
@@ -287,7 +292,9 @@ of their arities; so it should not be asking...  (but other things
 besides the code-generator need arity info!)
 -}
 
--- | An 'ArityInfo' of @n@ tells us that partial application of this
+-- | Arity Information
+--
+-- An 'ArityInfo' of @n@ tells us that partial application of this
 -- 'Id' to up to @n-1@ value arguments does essentially no work.
 --
 -- That is not necessarily the same as saying that it has @n@ leading
@@ -313,7 +320,9 @@ ppArityInfo n = hsep [text "Arity", int n]
 ************************************************************************
 -}
 
--- | Tells when the inlining is active.
+-- | Inline Pragma Information
+--
+-- Tells when the inlining is active.
 -- When it is active the thing may be inlined, depending on how
 -- big it is.
 --
@@ -362,7 +371,9 @@ In TidyPgm, when the LocalId becomes a GlobalId, its RULES are stripped off
 and put in the global list.
 -}
 
--- | Records the specializations of this 'Id' that we know about
+-- | Rule Information
+--
+-- Records the specializations of this 'Id' that we know about
 -- in the form of rewrite 'CoreRule's that target them
 data RuleInfo
   = RuleInfo
@@ -402,7 +413,9 @@ setRuleInfoHead fn (RuleInfo rules fvs)
 
 -- CafInfo is used to build Static Reference Tables (see simplStg/SRT.hs).
 
--- | Records whether an 'Id' makes Constant Applicative Form references
+-- | Constant applicative form Information
+--
+-- Records whether an 'Id' makes Constant Applicative Form references
 data CafInfo
         = MayHaveCafRefs                -- ^ Indicates that the 'Id' is for either:
                                         --

compiler/basicTypes/MkId.hs

@@ -458,6 +458,7 @@ type Unboxer = Var -> UniqSM ([Var], CoreExpr -> CoreExpr)
 data Boxer = UnitBox | Boxer (TCvSubst -> UniqSM ([Var], CoreExpr))
   -- Box:   build src arg using these rep vars
 
+-- | Data Constructor Boxer
 newtype DataConBoxer = DCB ([Type] -> [Var] -> UniqSM ([Var], [CoreBind]))
                        -- Bind these src-level vars, returning the
                        -- rep-level vars to bind in the pattern

compiler/basicTypes/Module.hs

@@ -180,7 +180,9 @@ import System.FilePath
 ************************************************************************
 -}
 
--- | Where a module lives on the file system: the actual locations
+-- | Module Location
+--
+-- Where a module lives on the file system: the actual locations
 -- of the .hs, .hi and .o files, if we have them
 data ModLocation
    = ModLocation {

compiler/basicTypes/NameEnv.hs

@@ -82,6 +82,7 @@ depAnal get_defs get_uses nodes
 ************************************************************************
 -}
 
+-- | Name Environment
 type NameEnv a = UniqFM a       -- Domain is Name
 
 emptyNameEnv       :: NameEnv a
@@ -131,7 +132,8 @@ disjointNameEnv x y     = isNullUFM (intersectUFM x y)
 
 lookupNameEnv_NF env n = expectJust "lookupNameEnv_NF" (lookupNameEnv env n)
 
--- Deterministic NameEnv
+-- | Deterministic Name Environment
+--
 -- See Note [Deterministic UniqFM] in UniqDFM for explanation why we need
 -- DNameEnv.
 type DNameEnv a = UniqDFM a

compiler/basicTypes/OccName.hs

@@ -228,6 +228,11 @@ demoteNameSpace TcClsName = Just DataName
 ************************************************************************
 -}
 
+-- | Occurrence Name
+--
+-- In this context that means:
+-- "classified (i.e. as a type name, value name, etc) but not qualified
+-- and not yet resolved"
 data OccName = OccName
     { occNameSpace  :: !NameSpace
     , occNameFS     :: !FastString

compiler/basicTypes/PatSyn.hs

@@ -45,7 +45,8 @@ import Data.List
 ************************************************************************
 -}
 
--- | A pattern synonym
+-- | Pattern Synonym
+--
 -- See Note [Pattern synonym representation]
 -- See Note [Pattern synonym signatures]
 data PatSyn

compiler/basicTypes/RdrName.hs

@@ -89,7 +89,9 @@ import Data.List( sortBy )
 ************************************************************************
 -}
 
--- | Do not use the data constructors of RdrName directly: prefer the family
+-- | Reader Name
+--
+-- Do not use the data constructors of RdrName directly: prefer the family
 -- of functions that creates them, such as 'mkRdrUnqual'
 --
 -- - Note: A Located RdrName will only have API Annotations if it is a
@@ -109,11 +111,15 @@ import Data.List( sortBy )
 -- For details on above see note [Api annotations] in ApiAnnotation
 data RdrName
   = Unqual OccName
-        -- ^ Used for ordinary, unqualified occurrences, e.g. @x@, @y@ or @Foo@.
+        -- ^ Unqualified  name
+        --
+        -- Used for ordinary, unqualified occurrences, e.g. @x@, @y@ or @Foo@.
         -- Create such a 'RdrName' with 'mkRdrUnqual'
 
   | Qual ModuleName OccName
-        -- ^ A qualified name written by the user in
+        -- ^ Qualified name
+        --
+        -- A qualified name written by the user in
         -- /source/ code.  The module isn't necessarily
         -- the module where the thing is defined;
         -- just the one from which it is imported.
@@ -121,14 +127,18 @@ data RdrName
         -- Create such a 'RdrName' with 'mkRdrQual'
 
   | Orig Module OccName
-        -- ^ An original name; the module is the /defining/ module.
+        -- ^ Original name
+        --
+        -- An original name; the module is the /defining/ module.
         -- This is used when GHC generates code that will be fed
         -- into the renamer (e.g. from deriving clauses), but where
         -- we want to say \"Use Prelude.map dammit\". One of these
         -- can be created with 'mkOrig'
 
   | Exact Name
-        -- ^ We know exactly the 'Name'. This is used:
+        -- ^ Exact name
+        --
+        -- We know exactly the 'Name'. This is used:
         --
         --  (1) When the parser parses built-in syntax like @[]@
         --      and @(,)@, but wants a 'RdrName' from it
@@ -319,7 +329,10 @@ instance Ord RdrName where
 ************************************************************************
 -}
 
--- | This environment is used to store local bindings (@let@, @where@, lambda, @case@).
+-- | Local Reader Environment
+--
+-- This environment is used to store local bindings
+-- (@let@, @where@, lambda, @case@).
 -- It is keyed by OccName, because we never use it for qualified names
 -- We keep the current mapping, *and* the set of all Names in scope
 -- Reason: see Note [Splicing Exact names] in RnEnv
@@ -405,6 +418,7 @@ the in-scope-name-set.
 ************************************************************************
 -}
 
+-- | Global Reader Environment
 type GlobalRdrEnv = OccEnv [GlobalRdrElt]
 -- ^ Keyed by 'OccName'; when looking up a qualified name
 -- we look up the 'OccName' part, and then check the 'Provenance'
@@ -431,7 +445,9 @@ type GlobalRdrEnv = OccEnv [GlobalRdrElt]
 --                  nameOccName (gre_name gre), but not always in the
 --                  case of record seectors; see greOccName
 
--- | An element of the 'GlobalRdrEnv'
+-- | Global Reader Element
+--
+-- An element of the 'GlobalRdrEnv'
 data GlobalRdrElt
   = GRE { gre_name :: Name
         , gre_par  :: Parent
@@ -1019,13 +1035,17 @@ shadowName env name
 ************************************************************************
 -}
 
--- | The 'ImportSpec' of something says how it came to be imported
+-- | Import Specification
+--
+-- The 'ImportSpec' of something says how it came to be imported
 -- It's quite elaborate so that we can give accurate unused-name warnings.
 data ImportSpec = ImpSpec { is_decl :: ImpDeclSpec,
                             is_item :: ImpItemSpec }
                 deriving( Eq, Ord, Data )
 
--- | Describes a particular import declaration and is
+-- | Import Declaration Specification
+--
+-- Describes a particular import declaration and is
 -- shared among all the 'Provenance's for that decl
 data ImpDeclSpec
   = ImpDeclSpec {
@@ -1040,7 +1060,9 @@ data ImpDeclSpec
         is_dloc     :: SrcSpan     -- ^ The location of the entire import declaration
     } deriving Data
 
--- | Describes import info a particular Name
+-- | Import Item Specification
+--
+-- Describes import info a particular Name
 data ImpItemSpec
   = ImpAll              -- ^ The import had no import list,
                         -- or had a hiding list

compiler/basicTypes/SrcLoc.hs

@@ -101,13 +101,16 @@ We keep information about the {\em definition} point for each entity;
 this is the obvious stuff:
 -}
 
--- | Represents a single point within a file
+-- | Real Source Location
+--
+-- Represents a single point within a file
 data RealSrcLoc
   = SrcLoc      FastString              -- A precise location (file name)
                 {-# UNPACK #-} !Int     -- line number, begins at 1
                 {-# UNPACK #-} !Int     -- column number, begins at 1
   deriving (Eq, Ord)
 
+-- | Source Location
 data SrcLoc
   = RealSrcLoc {-# UNPACK #-}!RealSrcLoc
   | UnhelpfulLoc FastString     -- Just a general indication
@@ -219,6 +222,8 @@ The end position is defined to be the column /after/ the end of the
 span.  That is, a span of (1,1)-(1,2) is one character long, and a
 span of (1,1)-(1,1) is zero characters long.
 -}
+
+-- | Real Source Span
 data RealSrcSpan
   = RealSrcSpan'
         { srcSpanFile     :: !FastString,
@@ -229,7 +234,9 @@ data RealSrcSpan
         }
   deriving Eq
 
--- | A 'SrcSpan' identifies either a specific portion of a text file
+-- | Source Span
+--
+-- A 'SrcSpan' identifies either a specific portion of a text file
 -- or a human-readable description of a location.
 data SrcSpan =
     RealSrcSpan !RealSrcSpan

compiler/basicTypes/UniqSupply.hs

@@ -46,7 +46,9 @@ import Data.Char
 ************************************************************************
 -}
 
--- | A value of type 'UniqSupply' is unique, and it can
+-- | Unique Supply
+--
+-- A value of type 'UniqSupply' is unique, and it can
 -- supply /one/ distinct 'Unique'.  Also, from the supply, one can
 -- also manufacture an arbitrary number of further 'UniqueSupply' values,
 -- which will be distinct from the first and from all others.

compiler/basicTypes/Unique.hs

@@ -87,7 +87,9 @@ The @Chars@ are ``tag letters'' that identify the @UniqueSupply@.
 Fast comparison is everything on @Uniques@:
 -}
 
--- | The type of unique identifiers that are used in many places in GHC
+-- | Unique identifier.
+--
+-- The type of unique identifiers that are used in many places in GHC
 -- for fast ordering and equality tests. You should generate these with
 -- the functions from the 'UniqSupply' module
 newtype Unique = MkUnique Int

compiler/basicTypes/Var.hs

@@ -101,32 +101,53 @@ import Data.Data
 -- large number of SOURCE imports of Id.hs :-(
 -}
 
+-- | Identifier
 type Id    = Var       -- A term-level identifier
                        --  predicate: isId
 
+-- | Coercion Variable
 type CoVar = Id        -- See Note [Evidence: EvIds and CoVars]
                        --   predicate: isCoVar
 
+-- |
 type NcId  = Id        -- A term-level (value) variable that is
                        -- /not/ an (unlifted) coercion
                        --    predicate: isNonCoVarId
 
+-- | Type or kind Variable
 type TyVar   = Var     -- Type *or* kind variable (historical)
 
+-- | Type or Kind Variable
 type TKVar   = Var     -- Type *or* kind variable (historical)
+
+-- | Type Variable
 type TypeVar = Var     -- Definitely a type variable
+
+-- | Kind Variable
 type KindVar = Var     -- Definitely a kind variable
                        -- See Note [Kind and type variables]
 
 -- See Note [Evidence: EvIds and CoVars]
+-- | Evidence Identifier
 type EvId   = Id        -- Term-level evidence: DictId, IpId, or EqVar
+
+-- | Evidence Variable
 type EvVar  = EvId      -- ...historical name for EvId
+
+-- | Dictionary Function Identifier
 type DFunId = Id        -- A dictionary function
+
+-- | Dictionary Identifier
 type DictId = EvId      -- A dictionary variable
+
+-- | Implicit parameter Identifier
 type IpId   = EvId      -- A term-level implicit parameter
+
+-- | Equality Variable
 type EqVar  = EvId      -- Boxed equality evidence
 
-type TyCoVar = Id       -- Type, kind, *or* coercion variable
+-- | Type or Coercion Variable
+type TyCoVar = Id       -- Type, *or* coercion variable
                         --   predicate: isTyCoVar
 
 {- Note [Evidence: EvIds and CoVars]
@@ -163,7 +184,9 @@ strictness).  The essential info about different kinds of @Vars@ is
 in its @VarDetails@.
 -}
 
--- | Essentially a typed 'Name', that may also contain some additional information
+-- | Variable
+--
+-- Essentially a typed 'Name', that may also contain some additional information
 -- about the 'Var' and it's use sites.
 data Var
   = TyVar {  -- Type and kind variables
@@ -193,6 +216,7 @@ data Var
         id_details :: IdDetails,        -- Stable, doesn't change
         id_info    :: IdInfo }          -- Unstable, updated by simplifier
 
+-- | Identifier Scope
 data IdScope    -- See Note [GlobalId/LocalId]
   = GlobalId
   | LocalId ExportFlag
@@ -321,7 +345,9 @@ updateVarTypeM f id = do { ty' <- f (varType id)
 *                                                                      *
 ********************************************************************* -}
 
--- | Is something required to appear in source Haskell ('Required'),
+-- | Argument Flag
+--
+-- Is something required to appear in source Haskell ('Required'),
 -- permitted by request ('Specified') (visible type application), or
 -- prohibited entirely from appearing in source Haskell ('Inferred')?
 -- See Note [TyBinders and ArgFlags] in TyCoRep
@@ -352,13 +378,17 @@ sameVis _        _        = True
 *                                                                      *
 ********************************************************************* -}
 
+-- Type Variable Binder
+--
 -- TyVarBndr is polymorphic in both tyvar and visiblity fields:
 --   * tyvar can be TyVar or IfaceTv
 --   * argf  can be ArgFlag or TyConBndrVis
 data TyVarBndr tyvar argf = TvBndr tyvar argf
   deriving( Data )
 
--- | A `TyVarBinder` is the binder of a ForAllTy
+-- | Type Variable Binder
+--
+-- A 'TyVarBinder' is the binder of a ForAllTy
 -- It's convenient to define this synonym here rather its natural
 -- home in TyCoRep, because it's used in DataCon.hs-boot
 type TyVarBinder = TyVarBndr TyVar ArgFlag

compiler/basicTypes/VarEnv.hs

@@ -195,7 +195,9 @@ uniqAway' (InScope set n) var
 ************************************************************************
 -}
 
--- | When we are comparing (or matching) types or terms, we are faced with
+-- | Rename Environment 2
+--
+-- When we are comparing (or matching) types or terms, we are faced with
 -- \"going under\" corresponding binders.  E.g. when comparing:
 --
 -- > \x. e1     ~   \y. e2
@@ -390,7 +392,9 @@ succeeding with [a -> v y], which is bogus of course.
 ************************************************************************
 -}
 
--- | When tidying up print names, we keep a mapping of in-scope occ-names
+-- | Tidy Environment
+--
+-- When tidying up print names, we keep a mapping of in-scope occ-names
 -- (the 'TidyOccEnv') and a Var-to-Var of the current renamings
 type TidyEnv = (TidyOccEnv, VarEnv Var)
 
@@ -405,10 +409,19 @@ emptyTidyEnv = (emptyTidyOccEnv, emptyVarEnv)
 ************************************************************************
 -}
 
+-- | Variable Environment
 type VarEnv elt     = UniqFM elt
+
+-- | Identifier Environment
 type IdEnv elt      = VarEnv elt
+
+-- | Type Variable Environment
 type TyVarEnv elt   = VarEnv elt
+
+-- | Type or Coercion Variable Environment
 type TyCoVarEnv elt = VarEnv elt
+
+-- | Coercion Variable Environment
 type CoVarEnv elt   = VarEnv elt
 
 emptyVarEnv       :: VarEnv a
@@ -504,8 +517,13 @@ modifyVarEnv_Directly mangle_fn env key
 -- See Note [Deterministic UniqFM] in UniqDFM for explanation why we need
 -- DVarEnv.
 
+-- | Deterministic Variable Environment
 type DVarEnv elt = UniqDFM elt
+
+-- | Deterministic Identifier Environment
 type DIdEnv elt = DVarEnv elt
+
+-- | Deterministic Type Variable Environment
 type DTyVarEnv elt = DVarEnv elt
 
 emptyDVarEnv :: DVarEnv a

compiler/basicTypes/VarSet.hs

@@ -53,15 +53,25 @@ import UniqFM( disjointUFM, pluralUFM, pprUFM )
 import UniqDFM( disjointUDFM, udfmToUfm )
 import Outputable (SDoc)
 
--- | A non-deterministic set of variables.
+-- | A non-deterministic Variable Set
+--
+-- A non-deterministic set of variables.
 -- See Note [Deterministic UniqFM] in UniqDFM for explanation why it's not
 -- deterministic and why it matters. Use DVarSet if the set eventually
 -- gets converted into a list or folded over in a way where the order
 -- changes the generated code, for example when abstracting variables.
 type VarSet       = UniqSet Var
+
+-- | Identifier Set
 type IdSet        = UniqSet Id
+
+-- | Type Variable Set
 type TyVarSet     = UniqSet TyVar
+
+-- | Coercion Variable Set
 type CoVarSet     = UniqSet CoVar
+
+-- | Type or Coercion Variable Set
 type TyCoVarSet   = UniqSet TyCoVar
 
 emptyVarSet     :: VarSet
@@ -203,9 +213,16 @@ pprVarSet = pprUFM
 -- See Note [Deterministic UniqFM] in UniqDFM for explanation why we need
 -- DVarSet.