Commit ca7e1ad3 authored by Ben Gamari's avatar Ben Gamari 🐢

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
parent e3e2e49a
......@@ -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
......
......@@ -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
......
......@@ -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:
--
......
......@@ -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
......
......@@ -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 {
......
......@@ -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
......
......@@ -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
......
......@@ -45,7 +45,8 @@ import Data.List
************************************************************************
-}
-- | A pattern synonym
-- | Pattern Synonym
--
-- See Note [Pattern synonym representation]
-- See Note [Pattern synonym signatures]
data PatSyn
......
......@@ -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
......
......@@ -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
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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.