Expanded abbreviations in Haddock documentation
authorBen Gamari <ben@smart-cactus.org>
Thu, 4 Aug 2016 12:36:09 +0000 (14:36 +0200)
committerBen Gamari <ben@smart-cactus.org>
Fri, 5 Aug 2016 08:40:45 +0000 (10:40 +0200)
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

24 files changed:
compiler/basicTypes/BasicTypes.hs
compiler/basicTypes/DataCon.hs
compiler/basicTypes/IdInfo.hs
compiler/basicTypes/MkId.hs
compiler/basicTypes/Module.hs
compiler/basicTypes/NameEnv.hs
compiler/basicTypes/OccName.hs
compiler/basicTypes/PatSyn.hs
compiler/basicTypes/RdrName.hs
compiler/basicTypes/SrcLoc.hs
compiler/basicTypes/UniqSupply.hs
compiler/basicTypes/Unique.hs
compiler/basicTypes/Var.hs
compiler/basicTypes/VarEnv.hs
compiler/basicTypes/VarSet.hs
compiler/hsSyn/HsBinds.hs
compiler/hsSyn/HsDecls.hs
compiler/hsSyn/HsDoc.hs
compiler/hsSyn/HsExpr.hs
compiler/hsSyn/HsImpExp.hs
compiler/hsSyn/HsLit.hs
compiler/hsSyn/HsPat.hs
compiler/hsSyn/HsSyn.hs
compiler/hsSyn/HsTypes.hs

index 2fc3833..aab0528 100644 (file)
@@ -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
index 7fcc5fb..6fda33a 100644 (file)
@@ -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
index 4d10f20..392c1ec 100644 (file)
@@ -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:
                                         --
index 512f8aa..151e1cf 100644 (file)
@@ -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
index b6b19d2..0bade7d 100644 (file)
@@ -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 {
index 024e3d8..640084b 100644 (file)
@@ -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
index 3b8943f..0727328 100644 (file)
@@ -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
index 3b51452..774879e 100644 (file)
@@ -45,7 +45,8 @@ import Data.List
 ************************************************************************
 -}
 
--- | A pattern synonym
+-- | Pattern Synonym
+--
 -- See Note [Pattern synonym representation]
 -- See Note [Pattern synonym signatures]
 data PatSyn
index bfac741..ba411af 100644 (file)
@@ -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
index 9c48eee..45d92d0 100644 (file)
@@ -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
index e7e44ca..9f97d49 100644 (file)
@@ -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.
index c42b825..0bbf861 100644 (file)
@@ -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
index 800e6d9..c7a6bfe 100644 (file)
@@ -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
index 92b6cc7..6e22417 100644 (file)
@@ -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
index b0151d8..a6e508a 100644 (file)
@@ -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.
 
+-- | Deterministic Variable Set
 type DVarSet     = UniqDSet Var
+
+-- | Deterministic Identifier Set
 type DIdSet      = UniqDSet Id
+
+-- | Deterministic Type Variable Set
 type DTyVarSet   = UniqDSet TyVar
+
+-- | Deterministic Type or Coercion Variable Set
 type DTyCoVarSet = UniqDSet TyCoVar
 
 emptyDVarSet :: DVarSet
index 58b33fb..2120e05 100644 (file)
@@ -60,40 +60,51 @@ Global bindings (where clauses)
 -- one for the left and one for the right.
 -- Other than during renaming, these will be the same.
 
+-- | Haskell Local Bindings
 type HsLocalBinds id = HsLocalBindsLR id id
 
--- | Bindings in a 'let' expression
+-- | Haskell Local Bindings with separate Left and Right identifier types
+--
+-- Bindings in a 'let' expression
 -- or a 'where' clause
 data HsLocalBindsLR idL idR
   = HsValBinds (HsValBindsLR idL idR)
+      -- ^ Haskell Value Bindings
+
          -- There should be no pattern synonyms in the HsValBindsLR
          -- These are *local* (not top level) bindings
          -- The parser accepts them, however, leaving the the
          -- renamer to report them
 
   | HsIPBinds  (HsIPBinds idR)
+      -- ^ Haskell Implicit Parameter Bindings
 
   | EmptyLocalBinds
+      -- ^ Empty Local Bindings
 
 deriving instance (DataId idL, DataId idR)
   => Data (HsLocalBindsLR idL idR)
 
+-- | Haskell Value Bindings
 type HsValBinds id = HsValBindsLR id id
 
--- | Value bindings (not implicit parameters)
+-- | Haskell Value bindings with separate Left and Right identifier types
+-- (not implicit parameters)
 -- Used for both top level and nested bindings
 -- May contain pattern synonym bindings
 data HsValBindsLR idL idR
-  = -- | Before renaming RHS; idR is always RdrName
+  = -- | Value Bindings In
+    --
+    -- Before renaming RHS; idR is always RdrName
     -- Not dependency analysed
     -- Recursive by default
     ValBindsIn
         (LHsBindsLR idL idR) [LSig idR]
 
-    -- | After renaming RHS; idR can be Name or Id
-    --  Dependency analysed,
-    -- later bindings in the list may depend on earlier
-    -- ones.
+    -- | Value Bindings Out
+    --
+    -- After renaming RHS; idR can be Name or Id Dependency analysed,
+    -- later bindings in the list may depend on earlier ones.
   | ValBindsOut
         [(RecFlag, LHsBinds idL)]
         [LSig Name]
@@ -101,15 +112,26 @@ data HsValBindsLR idL idR
 deriving instance (DataId idL, DataId idR)
   => Data (HsValBindsLR idL idR)
 
+-- | Located Haskell Binding
 type LHsBind  id = LHsBindLR  id id
+
+-- | Located Haskell Bindings
 type LHsBinds id = LHsBindsLR id id
+
+-- | Haskell Binding
 type HsBind   id = HsBindLR   id id
 
+-- | Located Haskell Bindings with separate Left and Right identifier types
 type LHsBindsLR idL idR = Bag (LHsBindLR idL idR)
+
+-- | Located Haskell Binding with separate Left and Right identifier types
 type LHsBindLR  idL idR = Located (HsBindLR idL idR)
 
+-- | Haskell Binding with separate Left and Right id's
 data HsBindLR idL idR
-  = -- | FunBind is used for both functions   @f x = e@
+  = -- | Function Binding
+    --
+    -- FunBind is used for both functions     @f x = e@
     -- and variables                          @f = \x -> e@
     --
     -- Reason 1: Special case for type inference: see 'TcBinds.tcMonoBinds'.
@@ -158,7 +180,9 @@ data HsBindLR idL idR
         fun_tick :: [Tickish Id]  -- ^ Ticks to put on the rhs, if any
     }
 
-  -- | The pattern is never a simple variable;
+  -- | Pattern Binding
+  --
+  -- The pattern is never a simple variable;
   -- That case is done by FunBind
   --
   --  - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnBang',
@@ -176,7 +200,9 @@ data HsBindLR idL idR
                -- the bound variables.
     }
 
-  -- | Dictionary binding and suchlike.
+  -- | Variable Binding
+  --
+  -- Dictionary binding and suchlike.
   -- All VarBinds are introduced by the type checker
   | VarBind {
         var_id     :: idL,
@@ -185,6 +211,7 @@ data HsBindLR idL idR
                                      -- (used for implication constraints only)
     }
 
+  -- | Abstraction Bindings
   | AbsBinds {                      -- Binds abstraction; TRANSLATION
         abs_tvs     :: [TyVar],
         abs_ev_vars :: [EvVar],  -- ^ Includes equality constraints
@@ -203,6 +230,7 @@ data HsBindLR idL idR
         abs_binds    :: LHsBinds idL
     }
 
+  -- | Abstraction Bindings Signature
   | AbsBindsSig {  -- Simpler form of AbsBinds, used with a type sig
                    -- in tcPolyCheck. Produces simpler desugaring and
                    -- is necessary to avoid #11405, comment:3.
@@ -217,6 +245,7 @@ data HsBindLR idL idR
                                        -- FunBind
     }
 
+  -- | Patterns Synonym Binding
   | PatSynBind (PatSynBind idL idR)
         -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnPattern',
         --          'ApiAnnotation.AnnLarrow','ApiAnnotation.AnnEqual',
@@ -240,6 +269,7 @@ deriving instance (DataId idL, DataId idR)
         --
         -- See Note [AbsBinds]
 
+-- | Abtraction Bindings Export
 data ABExport id
   = ABE { abe_poly      :: id    -- ^ Any INLINE pragmas is attached to this Id
         , abe_mono      :: id
@@ -254,6 +284,8 @@ data ABExport id
 --             'ApiAnnotation.AnnClose' @'}'@,
 
 -- For details on above see note [Api annotations] in ApiAnnotation
+
+-- | Pattern Synonym binding
 data PatSynBind idL idR
   = PSB { psb_id   :: Located idL,             -- ^ Name of the pattern synonym
           psb_fvs  :: PostRn idR NameSet,      -- ^ See Note [Bind free vars]
@@ -619,6 +651,7 @@ pprTicks pp_no_debug pp_when_debug
 ************************************************************************
 -}
 
+-- | Haskell Implicit Parameter Bindings
 data HsIPBinds id
   = IPBinds
         [LIPBind id]
@@ -629,6 +662,7 @@ deriving instance (DataId id) => Data (HsIPBinds id)
 isEmptyIPBinds :: HsIPBinds id -> Bool
 isEmptyIPBinds (IPBinds is ds) = null is && isEmptyTcEvBinds ds
 
+-- | Located Implicit Parameter Binding
 type LIPBind id = Located (IPBind id)
 -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnSemi' when in a
 --   list
@@ -672,6 +706,7 @@ signatures.  Then all the machinery to move them into place, etc.,
 serves for both.
 -}
 
+-- | Located Signature
 type LSig name = Located (Sig name)
 
 -- | Signatures and pragmas
@@ -810,20 +845,26 @@ data Sig name
 
 deriving instance (DataId name) => Data (Sig name)
 
-
+-- | Located Fixity Signature
 type LFixitySig name = Located (FixitySig name)
+
+-- | Fixity Signature
 data FixitySig name = FixitySig [Located name] Fixity
   deriving Data
 
--- | TsSpecPrags conveys pragmas from the type checker to the desugarer
+-- | Type checker Specialisation Pragmas
+--
+-- 'TcSpecPrags' conveys @SPECIALISE@ pragmas from the type checker to the desugarer
 data TcSpecPrags
   = IsDefaultMethod     -- ^ Super-specialised: a default method should
                         -- be macro-expanded at every call site
   | SpecPrags [LTcSpecPrag]
   deriving Data
 
+-- | Located Type checker Specification Pragmas
 type LTcSpecPrag = Located TcSpecPrag
 
+-- | Type checker Specification Pragma
 data TcSpecPrag
   = SpecPrag
         Id
@@ -963,14 +1004,16 @@ pprMinimalSig (L _ bf) = text "MINIMAL" <+> ppr (fmap unLoc bf)
 ************************************************************************
 -}
 
+-- | Haskell Pattern Synonym Details
 data HsPatSynDetails a
-  = InfixPatSyn a a
-  | PrefixPatSyn [a]
-  | RecordPatSyn [RecordPatSynField a]
+  = InfixPatSyn a a                    -- ^ Infix Pattern Synonym
+  | PrefixPatSyn [a]                   -- ^ Prefix Pattern Synonym
+  | RecordPatSyn [RecordPatSynField a] -- ^ Record Pattern Synonym
   deriving Data
 
 
 -- See Note [Record PatSyn Fields]
+-- | Record Pattern Synonym Field
 data RecordPatSynField a
   = RecordPatSynField {
       recordPatSynSelectorId :: a  -- Selector name visible in rest of the file
@@ -1061,6 +1104,7 @@ instance Traversable HsPatSynDetails where
     traverse f (PrefixPatSyn args) = PrefixPatSyn <$> traverse f args
     traverse f (RecordPatSyn args) = RecordPatSyn <$> traverse (traverse f) args
 
+-- | Haskell Pattern Synonym Direction
 data HsPatSynDir id
   = Unidirectional
   | ImplicitBidirectional
index 7bf10c9..24b13c4 100644 (file)
@@ -128,20 +128,21 @@ type LHsDecl id = Located (HsDecl id)
 
 -- | A Haskell Declaration
 data HsDecl id
-  = TyClD       (TyClDecl id)     -- ^ A type or class declaration.
-  | InstD       (InstDecl  id)    -- ^ An instance declaration.
-  | DerivD      (DerivDecl id)
-  | ValD        (HsBind id)
-  | SigD        (Sig id)
-  | DefD        (DefaultDecl id)
-  | ForD        (ForeignDecl id)
-  | WarningD    (WarnDecls id)
-  | AnnD        (AnnDecl id)
-  | RuleD       (RuleDecls id)
-  | VectD       (VectDecl id)
-  | SpliceD     (SpliceDecl id)   -- Includes quasi-quotes
-  | DocD        (DocDecl)
-  | RoleAnnotD  (RoleAnnotDecl id)
+  = TyClD       (TyClDecl id)      -- ^ Type or Class Declaration
+  | InstD       (InstDecl  id)     -- ^ Instance declaration
+  | DerivD      (DerivDecl id)     -- ^ Deriving declaration
+  | ValD        (HsBind id)        -- ^ Value declaration
+  | SigD        (Sig id)           -- ^ Signature declaration
+  | DefD        (DefaultDecl id)   -- ^ 'default' declaration
+  | ForD        (ForeignDecl id)   -- ^ Foreign declaration
+  | WarningD    (WarnDecls id)     -- ^ Warning declaration
+  | AnnD        (AnnDecl id)       -- ^ Annotation declaration
+  | RuleD       (RuleDecls id)     -- ^ Rule declaration
+  | VectD       (VectDecl id)      -- ^ Vectorise declaration
+  | SpliceD     (SpliceDecl id)    -- ^ Splice declaration
+                                   -- (Includes quasi-quotes)
+  | DocD        (DocDecl)          -- ^ Documentation comment declaration
+  | RoleAnnotD  (RoleAnnotDecl id) -- ^ Role annotation declaration
 deriving instance (DataId id) => Data (HsDecl id)
 
 
@@ -158,7 +159,9 @@ deriving instance (DataId id) => Data (HsDecl id)
 --
 -- The latter is for class methods only
 
--- | A 'HsDecl' is categorised into a 'HsGroup' before being
+-- | Haskell Group
+--
+-- A 'HsDecl' is categorised into a 'HsGroup' before being
 -- fed to the renamer.
 data HsGroup id
   = HsGroup {
@@ -300,7 +303,10 @@ data SpliceExplicitFlag = ExplicitSplice | -- <=> $(f x y)
                           ImplicitSplice   -- <=> f x y,  i.e. a naked top level expression
     deriving Data
 
+-- | Located Splice Declaration
 type LSpliceDecl name = Located (SpliceDecl name)
+
+-- | Splice Declaration
 data SpliceDecl id
   = SpliceDecl                  -- Top level splice
         (Located (HsSplice id))
@@ -449,6 +455,7 @@ Interface file code:
     suck in the dfun binding
 -}
 
+-- | Located Declaration of a Type or Class
 type LTyClDecl name = Located (TyClDecl name)
 
 -- | A type or class declaration.
@@ -741,6 +748,7 @@ See Note [Dependency analsis of type, class, and instance decls]
 in RnSource for more info.
 -}
 
+-- | Type or Class Group
 data TyClGroup name  -- See Note [TyClGroups and dependency analysis]
   = TyClGroup { group_tyclds :: [LTyClDecl name]
               , group_roles  :: [LRoleAnnotDecl name]
@@ -837,7 +845,10 @@ conditions.
 See also Note [Injective type families] in TyCon
 -}
 
+-- | Located type Family Result Signature
 type LFamilyResultSig name = Located (FamilyResultSig name)
+
+-- | type Family Result Signature
 data FamilyResultSig name = -- see Note [FamilyResultSig]
     NoSig
   -- ^ - 'ApiAnnotation.AnnKeywordId' :
@@ -860,7 +871,10 @@ data FamilyResultSig name = -- see Note [FamilyResultSig]
 
 deriving instance (DataId name) => Data (FamilyResultSig name)
 
+-- | Located type Family Declaration
 type LFamilyDecl name = Located (FamilyDecl name)
+
+-- | type Family Declaration
 data FamilyDecl name = FamilyDecl
   { fdInfo           :: FamilyInfo name              -- type/data, closed/open
   , fdLName          :: Located name                 -- type constructor
@@ -879,6 +893,7 @@ data FamilyDecl name = FamilyDecl
 
 deriving instance (DataId id) => Data (FamilyDecl id)
 
+-- | Located Injectivity Annotation
 type LInjectivityAnn name = Located (InjectivityAnn name)
 
 -- | If the user supplied an injectivity annotation it is represented using
@@ -977,6 +992,7 @@ instance Outputable (FamilyInfo name) where
 *                                                                      *
 ********************************************************************* -}
 
+-- | Haskell Data type Definition
 data HsDataDefn name   -- The payload of a data type defn
                        -- Used *both* for vanilla data declarations,
                        --       *and* for data family instances
@@ -1010,6 +1026,7 @@ data HsDataDefn name   -- The payload of a data type defn
    }
 deriving instance (DataId id) => Data (HsDataDefn id)
 
+-- | Haskell Deriving clause
 type HsDeriving name = Maybe (Located [LHsSigType name])
   -- ^ The optional 'deriving' clause of a data declaration
   --
@@ -1033,6 +1050,7 @@ data NewOrData
   | DataType                    -- ^ @data Blah ...@
   deriving( Eq, Data )                -- Needed because Demand derives Eq
 
+-- | Located data Constructor Declaration
 type LConDecl name = Located (ConDecl name)
       -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnSemi' when
       --   in a GADT constructor list
@@ -1062,6 +1080,8 @@ type LConDecl name = Located (ConDecl name)
 --            'ApiAnnotation.AnnForall','ApiAnnotation.AnnDot'
 
 -- For details on above see note [Api annotations] in ApiAnnotation
+
+-- | data Constructor Declaration
 data ConDecl name
   = ConDeclGADT
       { con_names   :: [Located name]
@@ -1092,6 +1112,7 @@ data ConDecl name
       }
 deriving instance (DataId name) => Data (ConDecl name)
 
+-- | Haskell data Constructor Declaration Details
 type HsConDeclDetails name
    = HsConDetails (LBangType name) (Located [LConDeclField name])
 
@@ -1217,14 +1238,18 @@ It is parameterised over its tfe_pats field:
 -}
 
 ----------------- Type synonym family instances -------------
+
+-- | Located Type Family Instance Equation
 type LTyFamInstEqn  name = Located (TyFamInstEqn  name)
   -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnSemi'
   --   when in a list
 
 -- For details on above see note [Api annotations] in ApiAnnotation
 
+-- | Located Type Family Default Equation
 type LTyFamDefltEqn name = Located (TyFamDefltEqn name)
 
+-- | Haskell Type Patterns
 type HsTyPats name = HsImplicitBndrs name [LHsType name]
             -- ^ Type patterns (with kind and type bndrs)
             -- See Note [Family instance declaration binders]
@@ -1258,11 +1283,16 @@ type patterns, i.e. fv(pat_tys).  Note in particular
    in the associated 'type' decl
 -}
 
+-- | Type Family Instance Equation
 type TyFamInstEqn  name = TyFamEqn name (HsTyPats name)
+
+-- | Type Family Default Equation
 type TyFamDefltEqn name = TyFamEqn name (LHsQTyVars name)
   -- See Note [Type family instance declarations in HsSyn]
 
--- | One equation in a type family instance declaration
+-- | Type Family Equation
+--
+-- One equation in a type family instance declaration
 -- See Note [Type family instance declarations in HsSyn]
 data TyFamEqn name pats
   = TyFamEqn
@@ -1275,7 +1305,10 @@ data TyFamEqn name pats
     -- For details on above see note [Api annotations] in ApiAnnotation
 deriving instance (DataId name, Data pats) => Data (TyFamEqn name pats)
 
+-- | Located Type Family Instance Declaration
 type LTyFamInstDecl name = Located (TyFamInstDecl name)
+
+-- | Type Family Instance Declaration
 data TyFamInstDecl name
   = TyFamInstDecl
        { tfid_eqn  :: LTyFamInstEqn name
@@ -1289,7 +1322,10 @@ deriving instance (DataId name) => Data (TyFamInstDecl name)
 
 ----------------- Data family instances -------------
 
+-- | Located Data Family Instance Declaration
 type LDataFamInstDecl name = Located (DataFamInstDecl name)
+
+-- | Data Family Instance Declaration
 data DataFamInstDecl name
   = DataFamInstDecl
        { dfid_tycon     :: Located name
@@ -1309,7 +1345,10 @@ deriving instance (DataId name) => Data (DataFamInstDecl name)
 
 ----------------- Class instances -------------
 
+-- | Located Class Instance Declaration
 type LClsInstDecl name = Located (ClsInstDecl name)
+
+-- | Class Instance Declaration
 data ClsInstDecl name
   = ClsInstDecl
       { cid_poly_ty :: LHsSigType name    -- Context => Class Instance-type
@@ -1336,7 +1375,10 @@ deriving instance (DataId id) => Data (ClsInstDecl id)
 
 ----------------- Instances of all kinds -------------
 
+-- | Located Instance Declaration
 type LInstDecl name = Located (InstDecl name)
+
+-- | Instance Declaration
 data InstDecl name  -- Both class and family instances
   = ClsInstD
       { cid_inst  :: ClsInstDecl name }
@@ -1448,8 +1490,10 @@ instDeclDataFamInsts inst_decls
 ************************************************************************
 -}
 
+-- | Located Deriving Declaration
 type LDerivDecl name = Located (DerivDecl name)
 
+-- | Deriving Declaration
 data DerivDecl name = DerivDecl
         { deriv_type         :: LHsSigType name
         , deriv_overlap_mode :: Maybe (Located OverlapMode)
@@ -1478,8 +1522,10 @@ for the parser to check that; we pass them all through in the abstract
 syntax, and that restriction must be checked in the front end.
 -}
 
+-- | Located Default Declaration
 type LDefaultDecl name = Located (DefaultDecl name)
 
+-- | Default Declaration
 data DefaultDecl name
   = DefaultDecl [LHsType name]
         -- ^ - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnDefault',
@@ -1506,9 +1552,11 @@ instance (OutputableBndrId name) => Outputable (DefaultDecl name) where
 --
 --  * the Boolean value indicates whether the pre-standard deprecated syntax
 --   has been used
---
+
+-- | Located Foreign Declaration
 type LForeignDecl name = Located (ForeignDecl name)
 
+-- | Foreign Declaration
 data ForeignDecl name
   = ForeignImport
       { fd_name   :: Located name          -- defines this name
@@ -1629,15 +1677,19 @@ instance Outputable ForeignExport where
 ************************************************************************
 -}
 
+-- | Located Rule Declarations
 type LRuleDecls name = Located (RuleDecls name)
 
   -- Note [Pragma source text] in BasicTypes
+-- | Rule Declarations
 data RuleDecls name = HsRules { rds_src   :: SourceText
                               , rds_rules :: [LRuleDecl name] }
 deriving instance (DataId name) => Data (RuleDecls name)
 
+-- | Located Rule Declaration
 type LRuleDecl name = Located (RuleDecl name)
 
+-- | Rule Declaration
 data RuleDecl name
   = HsRule                             -- Source rule
         (Located (SourceText,RuleName)) -- Rule name
@@ -1663,7 +1715,10 @@ deriving instance (DataId name) => Data (RuleDecl name)
 flattenRuleDecls :: [LRuleDecls name] -> [LRuleDecl name]
 flattenRuleDecls decls = concatMap (rds_rules . unLoc) decls
 
+-- | Located Rule Binder
 type LRuleBndr name = Located (RuleBndr name)
+
+-- | Rule Binder
 data RuleBndr name
   = RuleBndr (Located name)
   | RuleBndrSig (Located name) (LHsSigWcType name)
@@ -1714,8 +1769,10 @@ A vectorisation pragma, one of
   {-# VECTORISE SCALAR type T #-}
 -}
 
+-- | Located Vectorise Declaration
 type LVectDecl name = Located (VectDecl name)
 
+-- | Vectorise Declaration
 data VectDecl name
   = HsVect
       SourceText   -- Note [Pragma source text] in BasicTypes
@@ -1818,8 +1875,10 @@ instance (OutputableBndrId name) => Outputable (VectDecl name) where
 ************************************************************************
 -}
 
+-- | Located Documentation comment Declaration
 type LDocDecl = Located (DocDecl)
 
+-- | Documentation comment Declaration
 data DocDecl
   = DocCommentNext HsDocString
   | DocCommentPrev HsDocString
@@ -1847,18 +1906,20 @@ docDeclDoc (DocGroup _ d) = d
 We use exported entities for things to deprecate.
 -}
 
-
+-- | Located Warning Declarations
 type LWarnDecls name = Located (WarnDecls name)
 
  -- Note [Pragma source text] in BasicTypes
+-- | Warning pragma Declarations
 data WarnDecls name = Warnings { wd_src :: SourceText
                                , wd_warnings :: [LWarnDecl name]
                                }
   deriving Data
 
-
+-- | Located Warning pragma Declaration
 type LWarnDecl name = Located (WarnDecl name)
 
+-- | Warning pragma Declaration
 data WarnDecl name = Warning [Located name] WarningTxt
   deriving Data
 
@@ -1877,8 +1938,10 @@ instance OutputableBndr name => Outputable (WarnDecl name) where
 ************************************************************************
 -}
 
+-- | Located Annotation Declaration
 type LAnnDecl name = Located (AnnDecl name)
 
+-- | Annotation Declaration
 data AnnDecl name = HsAnnotation
                       SourceText -- Note [Pragma source text] in BasicTypes
                       (AnnProvenance name) (Located (HsExpr name))
@@ -1894,6 +1957,7 @@ instance (OutputableBndrId name) => Outputable (AnnDecl name) where
     ppr (HsAnnotation _ provenance expr)
       = hsep [text "{-#", pprAnnProvenance provenance, pprExpr (unLoc expr), text "#-}"]
 
+-- | Annotation Provenance
 data AnnProvenance name = ValueAnnProvenance (Located name)
                         | TypeAnnProvenance (Located name)
                         | ModuleAnnProvenance
@@ -1921,10 +1985,12 @@ pprAnnProvenance (TypeAnnProvenance (L _ name))
 ************************************************************************
 -}
 
+-- | Located Role Annotation Declaration
 type LRoleAnnotDecl name = Located (RoleAnnotDecl name)
 
 -- See #8185 for more info about why role annotations are
 -- top-level declarations
+-- | Role Annotation Declaration
 data RoleAnnotDecl name
   = RoleAnnotDecl (Located name)         -- type constructor
                   [Located (Maybe Role)] -- optional annotations
index e515936..d9c5dba 100644 (file)
@@ -14,9 +14,11 @@ import FastString
 
 import Data.Data
 
+-- | Haskell Documentation String
 newtype HsDocString = HsDocString FastString
   deriving (Eq, Show, Data)
 
+-- | Located Haskell Documentation String
 type LHsDocString = Located HsDocString
 
 instance Outputable HsDocString where
index b2c40ca..78e6ad7 100644 (file)
@@ -63,6 +63,7 @@ import qualified Language.Haskell.TH as TH (Q)
 
 -- * Expressions proper
 
+-- | Located Haskell Expression
 type LHsExpr id = Located (HsExpr id)
   -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnComma' when
   --   in a list
@@ -70,10 +71,15 @@ type LHsExpr id = Located (HsExpr id)
   -- For details on above see note [Api annotations] in ApiAnnotation
 
 -------------------------
--- | PostTcExpr is an evidence expression attached to the syntax tree by the
+-- | Post-Type checking Expression
+--
+-- PostTcExpr is an evidence expression attached to the syntax tree by the
 -- type checker (c.f. postTcType).
 type PostTcExpr  = HsExpr Id
--- | We use a PostTcTable where there are a bunch of pieces of evidence, more
+
+-- | Post-Type checking Table
+--
+-- We use a PostTcTable where there are a bunch of pieces of evidence, more
 -- than is convenient to keep individually.
 type PostTcTable = [(Name, PostTcExpr)]
 
@@ -84,7 +90,9 @@ noPostTcTable :: PostTcTable
 noPostTcTable = []
 
 -------------------------
--- | SyntaxExpr is like 'PostTcExpr', but it's filled in a little earlier,
+-- | Syntax Expression
+--
+-- SyntaxExpr is like 'PostTcExpr', but it's filled in a little earlier,
 -- by the renamer.  It's used for rebindable syntax.
 --
 -- E.g. @(>>=)@ is filled in before the renamer by the appropriate 'Name' for
@@ -136,6 +144,7 @@ instance (OutputableBndrId id) => Outputable (SyntaxExpr id) where
                     <> braces (ppr res_wrap)
       else ppr expr
 
+-- | Command Syntax Table (for Arrow syntax)
 type CmdSyntaxTable id = [(Name, HsExpr id)]
 -- See Note [CmdSyntaxTable]
 
@@ -673,13 +682,18 @@ data HsExpr id
 
 deriving instance (DataId id) => Data (HsExpr id)
 
--- | HsTupArg is used for tuple sections
---  (,a,) is represented by  ExplicitTuple [Missing ty1, Present a, Missing ty3]
---  Which in turn stands for (\x:ty1 \y:ty2. (x,a,y))
+-- | Located Haskell Tuple Argument
+--
+-- 'HsTupArg' is used for tuple sections
+-- @(,a,)@ is represented by
+-- @ExplicitTuple [Missing ty1, Present a, Missing ty3]@
+-- Which in turn stands for @(\x:ty1 \y:ty2. (x,a,y))@
 type LHsTupArg id = Located (HsTupArg id)
 -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnComma'
 
 -- For details on above see note [Api annotations] in ApiAnnotation
+
+-- | Haskell Tuple Argument
 data HsTupArg id
   = Present (LHsExpr id)     -- ^ The argument
   | Missing (PostTc id Type) -- ^ The argument is missing, but this is its type
@@ -978,6 +992,7 @@ ppr_expr (HsRecFld f) = ppr f
 
 -- We must tiresomely make the "id" parameter to the LHsWcType existential
 -- because it's different in the HsAppType case and the HsAppTypeOut case
+-- | Located Haskell Wildcard Type Expression
 data LHsWcTypeX = forall id. (OutputableBndrId id) => LHsWcTypeX (LHsWcType id)
 
 ppr_apps :: (OutputableBndrId id)
@@ -1075,8 +1090,10 @@ isAtomicHsExpr _                 = False
 We re-use HsExpr to represent these.
 -}
 
+-- | Located Haskell Command (for arrow syntax)
 type LHsCmd id = Located (HsCmd id)
 
+-- | Haskell Command (e.g. a "statement" in an Arrow proc block)
 data HsCmd id
   -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.Annlarrowtail',
   --          'ApiAnnotation.Annrarrowtail','ApiAnnotation.AnnLarrowtail',
@@ -1161,6 +1178,7 @@ data HsCmd id
                                -- Then (HsCmdWrap wrap cmd) :: arg2 --> res
 deriving instance (DataId id) => Data (HsCmd id)
 
+-- | Haskell Array Application Type
 data HsArrAppType = HsHigherOrderApp | HsFirstOrderApp
   deriving Data
 
@@ -1170,8 +1188,10 @@ This may occur inside a proc (where the stack is empty) or as an
 argument of a command-forming operator.
 -}
 
+-- | Located Haskell Top-level Command
 type LHsCmdTop id = Located (HsCmdTop id)
 
+-- | Haskell Top-level Command
 data HsCmdTop id
   = HsCmdTop (LHsCmd id)
              (PostTc id Type)   -- Nested tuple of inputs on the command's stack
@@ -1273,6 +1293,7 @@ instance (OutputableBndrId id) => Outputable (HsCmdTop id) where
 ************************************************************************
 -}
 
+-- | Haskell Record Bindings
 type HsRecordBinds id = HsRecFields id (LHsExpr id)
 
 {-
@@ -1307,6 +1328,7 @@ data MatchGroup id body
      -- where there are n patterns
 deriving instance (Data body,DataId id) => Data (MatchGroup id body)
 
+-- | Located Match
 type LMatch id body = Located (Match id body)
 -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnSemi' when in a
 --   list
@@ -1389,7 +1411,9 @@ matchGroupArity (MG { mg_alts = alts })
 hsLMatchPats :: LMatch id body -> [LPat id]
 hsLMatchPats (L _ (Match _ pats _ _)) = pats
 
--- | GRHSs are used both for pattern bindings and for Matches
+-- | Guarded Right-Hand Sides
+--
+-- GRHSs are used both for pattern bindings and for Matches
 --
 --  - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnVbar',
 --        'ApiAnnotation.AnnEqual','ApiAnnotation.AnnWhere',
@@ -1404,6 +1428,7 @@ data GRHSs id body
     }
 deriving instance (Data body,DataId id) => Data (GRHSs id body)
 
+-- | Located Guarded Right-Hand Side
 type LGRHS id body = Located (GRHS id body)
 
 -- | Guarded Right Hand Side.
@@ -1492,19 +1517,37 @@ pp_rhs ctxt rhs = matchSeparator ctxt <+> pprDeeper (ppr rhs)
 ************************************************************************
 -}
 
+-- | Located @do@ block Statement
 type LStmt id body = Located (StmtLR id id body)
+
+-- | Located Statement with separate Left and Right id's
 type LStmtLR idL idR body = Located (StmtLR idL idR body)
 
+-- | @do@ block Statement
 type Stmt id body = StmtLR id id body
 
+-- | Command Located Statement
 type CmdLStmt   id = LStmt id (LHsCmd  id)
+
+-- | Command Statement
 type CmdStmt    id = Stmt  id (LHsCmd  id)
+
+-- | Expression Located Statement
 type ExprLStmt  id = LStmt id (LHsExpr id)
+
+-- | Expression Statement
 type ExprStmt   id = Stmt  id (LHsExpr id)
 
+-- | Guard Located Statement
 type GuardLStmt id = LStmt id (LHsExpr id)
+
+-- | Guard Statement
 type GuardStmt  id = Stmt  id (LHsExpr id)
+
+-- | Ghci Located Statemnt
 type GhciLStmt  id = LStmt id (LHsExpr id)
+
+-- | Ghci Statement
 type GhciStmt   id = Stmt  id (LHsExpr id)
 
 -- The SyntaxExprs in here are used *only* for do-notation and monad
@@ -1645,6 +1688,7 @@ data TransForm   -- The 'f' below is the 'using' function, 'e' is the by functio
   | GroupForm    -- then group using f   or    then group by e using f (depending on trS_by)
   deriving Data
 
+-- | Parenthesised Statement Block
 data ParStmtBlock idL idR
   = ParStmtBlock
         [ExprLStmt idL]
@@ -1652,6 +1696,7 @@ data ParStmtBlock idL idR
         (SyntaxExpr idR)   -- The return operator
 deriving instance (DataId idL, DataId idR) => Data (ParStmtBlock idL idR)
 
+-- | Applicative Argument
 data ApplicativeArg idL idR
   = ApplicativeArgOne            -- pat <- expr (pat must be irrefutable)
       (LPat idL)
@@ -1928,6 +1973,7 @@ pprQuals quals = interpp'SP quals
 ************************************************************************
 -}
 
+-- | Haskell Splice
 data HsSplice id
    = HsTypedSplice       --  $$z  or $$(f 4)
         id               -- A unique name to identify this splice point
@@ -1983,11 +2029,13 @@ instance Data ThModFinalizers where
   dataTypeOf a  = mkDataType "HsExpr.ThModFinalizers" [toConstr a]
 #endif
 
--- | Values that can result from running a splice.
+-- | Haskell Spliced Thing
+--
+-- Values that can result from running a splice.
 data HsSplicedThing id
-    = HsSplicedExpr (HsExpr id)
-    | HsSplicedTy   (HsType id)
-    | HsSplicedPat  (Pat id)
+    = HsSplicedExpr (HsExpr id) -- ^ Haskell Spliced Expression
+    | HsSplicedTy   (HsType id) -- ^ Haskell Spliced Type
+    | HsSplicedPat  (Pat id)    -- ^ Haskell Spilced Pattern
   deriving Typeable
 
 deriving instance (DataId id) => Data (HsSplicedThing id)
@@ -1995,6 +2043,7 @@ deriving instance (DataId id) => Data (HsSplicedThing id)
 -- See Note [Pending Splices]
 type SplicePointName = Name
 
+-- | Pending Renamer Splice
 data PendingRnSplice
   = PendingRnSplice UntypedSpliceFlavour SplicePointName (LHsExpr Name)
   deriving Data
@@ -2006,6 +2055,7 @@ data UntypedSpliceFlavour
   | UntypedDeclSplice
   deriving Data
 
+-- | Pending Type-checker Splice
 data PendingTcSplice
   = PendingTcSplice SplicePointName (LHsExpr Id)
   deriving Data
@@ -2111,6 +2161,7 @@ ppr_splice herald n e
                  HsVar _ -> pp_as_was
                  _ -> parens pp_as_was
 
+-- | Haskell Bracket
 data HsBracket id = ExpBr (LHsExpr id)   -- [|  expr  |]
                   | PatBr (LPat id)      -- [p| pat   |]
                   | DecBrL [LHsDecl id]  -- [d| decls |]; result of parser
@@ -2160,6 +2211,7 @@ instance Outputable PendingTcSplice where
 ************************************************************************
 -}
 
+-- | Arithmetic Sequence Information
 data ArithSeqInfo id
   = From            (LHsExpr id)
   | FromThen        (LHsExpr id)
@@ -2195,7 +2247,9 @@ instance Outputable FunctionFixity where
   ppr Prefix = text "Prefix"
   ppr Infix  = text "Infix"
 
--- | Context of a Match
+-- | Haskell Match Context
+--
+-- Context of a Match
 data HsMatchContext id
   = FunRhs (Located id) FunctionFixity -- ^Function binding for f, fixity
   | LambdaExpr                  -- ^Patterns of a lambda
@@ -2217,6 +2271,7 @@ data HsMatchContext id
   deriving Functor
 deriving instance (DataIdPost id) => Data (HsMatchContext id)
 
+-- | Haskell Statement Context
 data HsStmtContext id
   = ListComp
   | MonadComp
index beecd60..6d709cc 100644 (file)
@@ -32,6 +32,7 @@ import Data.Data
 One per \tr{import} declaration in a module.
 -}
 
+-- | Located Import Declaration
 type LImportDecl name = Located (ImportDecl name)
         -- ^ When in a list this may have
         --
@@ -39,7 +40,9 @@ type LImportDecl name = Located (ImportDecl name)
 
         -- For details on above see note [Api annotations] in ApiAnnotation
 
--- | A single Haskell @import@ declaration.
+-- | Import Declaration
+--
+-- A single Haskell @import@ declaration.
 data ImportDecl name
   = ImportDecl {
       ideclSourceSrc :: Maybe SourceText,
@@ -127,6 +130,7 @@ instance (OutputableBndr name, HasOccName name) => Outputable (ImportDecl name)
 ************************************************************************
 -}
 
+-- | Located Import or Export
 type LIE name = Located (IE name)
         -- ^ When in a list this may have
         --
@@ -137,18 +141,26 @@ type LIE name = Located (IE name)
 -- | Imported or exported entity.
 data IE name
   = IEVar       (Located name)
-        -- ^ - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnPattern',
+        -- ^ Imported or Exported Variable
+        --
+        -- - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnPattern',
         --             'ApiAnnotation.AnnType'
 
         -- For details on above see note [Api annotations] in ApiAnnotation
         -- See Note [Located RdrNames] in HsExpr
-  | IEThingAbs  (Located name)     -- ^ Class/Type (can't tell)
+  | IEThingAbs  (Located name)
+        -- ^ Imported or exported Thing with Absent list
+        --
+        -- The thing is a Class/Type (can't tell)
         --  - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnPattern',
         --             'ApiAnnotation.AnnType','ApiAnnotation.AnnVal'
 
         -- For details on above see note [Api annotations] in ApiAnnotation
         -- See Note [Located RdrNames] in HsExpr
-  | IEThingAll  (Located name)     -- ^ Class/Type plus all methods/constructors
+  | IEThingAll  (Located name)
+        -- ^ Imported or exported Thing with All imported or exported
+        --
+        -- The thing is a Class/Type and the All refers to methods/constructors
         --
         -- - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnOpen',
         --       'ApiAnnotation.AnnDotdot','ApiAnnotation.AnnClose',
@@ -161,15 +173,20 @@ data IE name
                 IEWildcard
                 [Located name]
                 [Located (FieldLbl name)]
-                 -- ^ Class/Type plus some methods/constructors
-                 -- and record fields; see Note [IEThingWith]
+        -- ^ Imported or exported Thing With given imported or exported
+        --
+        -- The thing is a Class/Type and the imported or exported things are
+        -- methods/constructors and record fields; see Note [IEThingWith]
         -- - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnOpen',
         --                                   'ApiAnnotation.AnnClose',
         --                                   'ApiAnnotation.AnnComma',
         --                                   'ApiAnnotation.AnnType'
 
         -- For details on above see note [Api annotations] in ApiAnnotation
-  | IEModuleContents  (Located ModuleName) -- ^ (Export Only)
+  | IEModuleContents  (Located ModuleName)
+        -- ^ Imported or exported module contents
+        --
+        -- (Export Only)
         --
         -- - 'ApiAnnotation.AnnKeywordId's : 'ApiAnnotation.AnnModule'
 
@@ -179,6 +196,7 @@ data IE name
   | IEDocNamed          String           -- ^ Reference to named doc
   deriving (Eq, Data)
 
+-- | Imported or Exported Wildcard
 data IEWildcard = NoIEWildcard | IEWildcard Int deriving (Eq, Data)
 
 {-
index 18746c0..4cf5719 100644 (file)
@@ -38,25 +38,39 @@ import Data.Data hiding ( Fixity )
 
 -- Note [Literal source text] in BasicTypes for SourceText fields in
 -- the following
+-- | Haskell Literal
 data HsLit
-  = HsChar          SourceText Char        -- Character
-  | HsCharPrim      SourceText Char        -- Unboxed character
-  | HsString        SourceText FastString  -- String
-  | HsStringPrim    SourceText ByteString  -- Packed bytes
-  | HsInt           SourceText Integer     -- Genuinely an Int; arises from
-                                       --     TcGenDeriv, and from TRANSLATION
-  | HsIntPrim       SourceText Integer     -- literal Int#
-  | HsWordPrim      SourceText Integer     -- literal Word#
-  | HsInt64Prim     SourceText Integer     -- literal Int64#
-  | HsWord64Prim    SourceText Integer     -- literal Word64#
-  | HsInteger       SourceText Integer Type -- Genuinely an integer; arises only
-                                          --   from TRANSLATION (overloaded
-                                          --   literals are done with HsOverLit)
-  | HsRat           FractionalLit Type -- Genuinely a rational; arises only from
-                                       --   TRANSLATION (overloaded literals are
-                                       --   done with HsOverLit)
-  | HsFloatPrim     FractionalLit      -- Unboxed Float
-  | HsDoublePrim    FractionalLit      -- Unboxed Double
+  = HsChar          SourceText Char
+      -- ^ Character
+  | HsCharPrim      SourceText Char
+      -- ^ Unboxed character
+  | HsString        SourceText FastString
+      -- ^ String
+  | HsStringPrim    SourceText ByteString
+      -- ^ Packed bytes
+  | HsInt           SourceText Integer
+      -- ^ Genuinely an Int; arises from
+      -- @TcGenDeriv@, and from TRANSLATION
+  | HsIntPrim       SourceText Integer
+      -- ^ literal @Int#@
+  | HsWordPrim      SourceText Integer
+      -- ^ literal @Word#@
+  | HsInt64Prim     SourceText Integer
+      -- ^ literal @Int64#@
+  | HsWord64Prim    SourceText Integer
+      -- ^ literal @Word64#@
+  | HsInteger       SourceText Integer Type
+      -- ^ Genuinely an integer; arises only
+      -- from TRANSLATION (overloaded
+      -- literals are done with HsOverLit)
+  | HsRat           FractionalLit Type
+      -- ^ Genuinely a rational; arises only from
+      -- TRANSLATION (overloaded literals are
+      -- done with HsOverLit)
+  | HsFloatPrim     FractionalLit
+      -- ^ Unboxed Float
+  | HsDoublePrim    FractionalLit
+      -- ^ Unboxed Double
   deriving Data
 
 instance Eq HsLit where
@@ -75,7 +89,8 @@ instance Eq HsLit where
   (HsDoublePrim x1)   == (HsDoublePrim x2)   = x1==x2
   _                   == _                   = False
 
-data HsOverLit id       -- An overloaded literal
+-- | Haskell Overloaded Literal
+data HsOverLit id
   = OverLit {
         ol_val :: OverLitVal,
         ol_rebindable :: PostRn id Bool, -- Note [ol_rebindable]
@@ -85,10 +100,11 @@ deriving instance (DataId id) => Data (HsOverLit id)
 
 -- Note [Literal source text] in BasicTypes for SourceText fields in
 -- the following
+-- | Overloaded Literal Value
 data OverLitVal
-  = HsIntegral   !SourceText !Integer    -- Integer-looking literals;
-  | HsFractional !FractionalLit          -- Frac-looking literals
-  | HsIsString   !SourceText !FastString -- String-looking literals
+  = HsIntegral   !SourceText !Integer    -- Integer-looking literals;
+  | HsFractional !FractionalLit          -- Frac-looking literals
+  | HsIsString   !SourceText !FastString -- String-looking literals
   deriving Data
 
 overLitType :: HsOverLit a -> PostTc a Type
index 719cd97..56e736a 100644 (file)
@@ -69,46 +69,51 @@ type OutPat id = LPat id        -- No 'In' constructors
 
 type LPat id = Located (Pat id)
 
--- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnBang'
+-- | Pattern
+--
+-- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnBang'
 
 -- For details on above see note [Api annotations] in ApiAnnotation
 data Pat id
   =     ------------ Simple patterns ---------------
-    WildPat     (PostTc id Type)        -- Wild card
+    WildPat     (PostTc id Type)        -- ^ Wildcard Pattern
         -- The sole reason for a type on a WildPat is to
         -- support hsPatType :: Pat Id -> Type
 
-  | VarPat      (Located id) -- Variable
+  | VarPat      (Located id) -- ^ Variable Pattern
+
                              -- See Note [Located RdrNames] in HsExpr
-  | LazyPat     (LPat id)               -- Lazy pattern
+  | LazyPat     (LPat id)               -- ^ Lazy Pattern
     -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnTilde'
 
     -- For details on above see note [Api annotations] in ApiAnnotation
 
-  | AsPat       (Located id) (LPat id)  -- As pattern
+  | AsPat       (Located id) (LPat id)  -- As pattern
     -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnAt'
 
     -- For details on above see note [Api annotations] in ApiAnnotation
 
-  | ParPat      (LPat id)               -- Parenthesised pattern
+  | ParPat      (LPat id)               -- Parenthesised pattern
                                         -- See Note [Parens in HsSyn] in HsExpr
     -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen' @'('@,
     --                                    'ApiAnnotation.AnnClose' @')'@
 
     -- For details on above see note [Api annotations] in ApiAnnotation
-  | BangPat     (LPat id)               -- Bang pattern
+  | BangPat     (LPat id)               -- Bang pattern
     -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnBang'
 
     -- For details on above see note [Api annotations] in ApiAnnotation
 
         ------------ Lists, tuples, arrays ---------------
-  | ListPat     [LPat id]                            -- Syntactic list
-                (PostTc id Type)                     -- The type of the elements
+  | ListPat     [LPat id]
+                (PostTc id Type)                        -- The type of the elements
                 (Maybe (PostTc id Type, SyntaxExpr id)) -- For rebindable syntax
                    -- For OverloadedLists a Just (ty,fn) gives
                    -- overall type of the pattern, and the toList
                    -- function to convert the scrutinee to a list value
-    -- ^ - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen' @'['@,
+    -- ^ Syntactic List
+    --
+    -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen' @'['@,
     --                                    'ApiAnnotation.AnnClose' @']'@
 
     -- For details on above see note [Api annotations] in ApiAnnotation
@@ -132,7 +137,9 @@ data Pat id
         -- of the tuple is of type 'a' not Int.  See selectMatchVar
         -- (June 14: I'm not sure this comment is right; the sub-patterns
         --           will be wrapped in CoPats, no?)
-    -- ^ - 'ApiAnnotation.AnnKeywordId' :
+    -- ^ Tuple sub-patterns
+    --
+    -- - 'ApiAnnotation.AnnKeywordId' :
     --            'ApiAnnotation.AnnOpen' @'('@ or @'(#'@,
     --            'ApiAnnotation.AnnClose' @')'@ or  @'#)'@
 
@@ -142,7 +149,9 @@ data Pat id
                 (PostTc id [Type]) -- PlaceHolder before typechecker, filled in
                                    -- afterwards with the types of the
                                    -- alternative
-    -- ^ - 'ApiAnnotation.AnnKeywordId' :
+    -- ^ Anonymous sum pattern
+    --
+    -- - 'ApiAnnotation.AnnKeywordId' :
     --            'ApiAnnotation.AnnOpen' @'(#'@,
     --            'ApiAnnotation.AnnClose' @'#)'@
 
@@ -156,6 +165,7 @@ data Pat id
         ------------ Constructor patterns ---------------
   | ConPatIn    (Located id)
                 (HsConPatDetails id)
+    -- ^ Constructor Pattern In
 
   | ConPatOut {
         pat_con     :: Located ConLike,
@@ -175,6 +185,7 @@ data Pat id
                                         -- Only relevant for pattern-synonyms;
                                         --   ignored for data cons
     }
+    -- ^ Constructor Pattern Out
 
         ------------ View patterns ---------------
   -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnRarrow'
@@ -185,19 +196,22 @@ data Pat id
                   (PostTc id Type)  -- The overall type of the pattern
                                     -- (= the argument type of the view function)
                                     -- for hsPatType.
+    -- ^ View Pattern
 
         ------------ Pattern splices ---------------
   -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen' @'$('@
   --        'ApiAnnotation.AnnClose' @')'@
 
   -- For details on above see note [Api annotations] in ApiAnnotation
-  | SplicePat       (HsSplice id)   -- Includes quasi-quotes
+  | SplicePat       (HsSplice id)   -- ^ Splice Pattern (Includes quasi-quotes)
 
         ------------ Literal and n+k patterns ---------------
-  | LitPat          HsLit               -- Used for *non-overloaded* literal patterns:
+  | LitPat          HsLit               -- ^ Literal Pattern
+                                        -- Used for *non-overloaded* literal patterns:
                                         -- Int#, Char#, Int, Char, String, etc.
 
-  | NPat                -- Used for all overloaded literals,
+  | NPat                -- Natural Pattern
+                        -- Used for all overloaded literals,
                         -- including overloaded strings with -XOverloadedStrings
                     (Located (HsOverLit id))    -- ALWAYS positive
                     (Maybe (SyntaxExpr id))     -- Just (Name of 'negate') for negative
@@ -207,7 +221,9 @@ data Pat id
                                                 -- different than the literal's type
                                                 -- if (==) or negate changes the type
 
-  -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnVal' @'+'@
+  -- ^ Natural Pattern
+  --
+  -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnVal' @'+'@
 
   -- For details on above see note [Api annotations] in ApiAnnotation
   | NPlusKPat       (Located id)        -- n+k pattern
@@ -219,6 +235,7 @@ data Pat id
                     (SyntaxExpr id)     -- (>=) function, of type t1->t2->Bool
                     (SyntaxExpr id)     -- Name of '-' (see RnEnv.lookupSyntaxName)
                     (PostTc id Type)    -- Type of overall pattern
+  -- ^ n+k pattern
 
         ------------ Pattern type signatures ---------------
   -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnDcolon'
@@ -227,19 +244,24 @@ data Pat id
   | SigPatIn        (LPat id)                 -- Pattern with a type signature
                     (LHsSigWcType id)         -- Signature can bind both
                                               -- kind and type vars
+    -- ^ Pattern with a type signature
 
-  | SigPatOut       (LPat id)           -- Pattern with a type signature
+  | SigPatOut       (LPat id)
                     Type
+    -- ^ Pattern with a type signature
 
         ------------ Pattern coercions (translation only) ---------------
-  | CoPat       HsWrapper               -- If co :: t1 ~ t2, p :: t2,
+  | CoPat       HsWrapper               -- Coercion Pattern
+                                        -- If co :: t1 ~ t2, p :: t2,
                                         -- then (CoPat co p) :: t1
                 (Pat id)                -- Why not LPat?  Ans: existing locn will do
                 Type                    -- Type of whole pattern, t1
         -- During desugaring a (CoPat co pat) turns into a cast with 'co' on
         -- the scrutinee, followed by a match on 'pat'
+    -- ^ Coercion Pattern
 deriving instance (DataId id) => Data (Pat id)
 
+-- | Haskell Constructor Pattern Details
 type HsConPatDetails id = HsConDetails (LPat id) (HsRecFields id (LPat id))
 
 hsConPatArgs :: HsConPatDetails id -> [LPat id]
@@ -247,9 +269,10 @@ hsConPatArgs (PrefixCon ps)   = ps
 hsConPatArgs (RecCon fs)      = map (hsRecFieldArg . unLoc) (rec_flds fs)
 hsConPatArgs (InfixCon p1 p2) = [p1,p2]
 
+-- | Haskell Record Fields
+--
 -- HsRecFields is used only for patterns and expressions (not data type
 -- declarations)
-
 data HsRecFields id arg         -- A bunch of record fields
                                 --      { x = 3, y = True }
         -- Used for both expressions and patterns
@@ -273,14 +296,24 @@ deriving instance (DataId id, Data arg) => Data (HsRecFields id arg)
 --                     the first 'n' being the user-written ones
 --                     and the remainder being 'filled in' implicitly
 
+-- | Located Haskell Record Field
 type LHsRecField' id arg = Located (HsRecField' id arg)
+
+-- | Located Haskell Record Field
 type LHsRecField  id arg = Located (HsRecField  id arg)
+
+-- | Located Haskell Record Update Field
 type LHsRecUpdField id   = Located (HsRecUpdField id)
 
+-- | Haskell Record Field
 type HsRecField    id arg = HsRecField' (FieldOcc id) arg
+
+-- | Haskell Record Update Field
 type HsRecUpdField id     = HsRecField' (AmbiguousFieldOcc id) (LHsExpr id)
 
--- |  - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnEqual',
+-- | Haskell Record Field
+--
+-- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnEqual',
 --
 -- For details on above see note [Api annotations] in ApiAnnotation
 data HsRecField' id arg = HsRecField {
index 1cfb8b8..1e5a4bb 100644 (file)
@@ -54,7 +54,9 @@ import Module           ( ModuleName )
 -- libraries:
 import Data.Data hiding ( Fixity )
 
--- | All we actually declare here is the top-level structure for a module.
+-- | Haskell Module
+--
+-- All we actually declare here is the top-level structure for a module.
 data HsModule name
   = HsModule {
       hsmodName :: Maybe (Located ModuleName),
index bf98ca3..008baef 100644 (file)
@@ -104,7 +104,10 @@ import qualified Data.Semigroup as Semigroup
 ************************************************************************
 -}
 
+-- | Located Bang Type
 type LBangType name = Located (BangType name)
+
+-- | Bang Type
 type BangType name  = HsType name       -- Bangs are in the HsType data type
 
 getBangType :: LHsType a -> LHsType a
@@ -219,19 +222,26 @@ Note carefully:
 
 -}
 
+-- | Located Haskell Context
 type LHsContext name = Located (HsContext name)
       -- ^ 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnUnit'
 
       -- For details on above see note [Api annotations] in ApiAnnotation
 
+-- | Haskell Context
 type HsContext name = [LHsType name]
 
+-- | Located Haskell Type
 type LHsType name = Located (HsType name)
       -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnComma' when
       --   in a list
 
       -- For details on above see note [Api annotations] in ApiAnnotation
+
+-- | Haskell Kind
 type HsKind name = HsType name
+
+-- | Located Haskell Kind
 type LHsKind name = Located (HsKind name)
       -- ^ 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnDcolon'
 
@@ -241,9 +251,11 @@ type LHsKind name = Located (HsKind name)
 --             LHsQTyVars
 --  The explicitly-quantified binders in a data/type declaration
 
+-- | Located Haskell Type Variable Binder
 type LHsTyVarBndr name = Located (HsTyVarBndr name)
                          -- See Note [HsType binders]
 
+-- | Located Haskell Quantified Type Variables
 data LHsQTyVars name   -- See Note [HsType binders]
   = HsQTvs { hsq_implicit :: PostRn name [Name]      -- implicit (dependent) variables
            , hsq_explicit :: [LHsTyVarBndr name]     -- explicit variables
@@ -278,11 +290,13 @@ isEmptyLHsQTvs _                = False
 --    * Pattern type signatures (SigPatIn)
 -- In the last of these, wildcards can happen, so we must accommodate them
 
+-- | Haskell Implicit Binders
 data HsImplicitBndrs name thing   -- See Note [HsType binders]
   = HsIB { hsib_vars :: PostRn name [Name] -- Implicitly-bound kind & type vars
          , hsib_body :: thing              -- Main payload (type or list of types)
     }
 
+-- | Haskell Wildcard Binders
 data HsWildCardBndrs name thing
     -- See Note [HsType binders]
     -- See Note [The wildcard story for types]
@@ -302,8 +316,13 @@ deriving instance (Data name, Data thing, Data (PostRn name [Name]))
 deriving instance (Data name, Data thing, Data (PostRn name [Name]))
   => Data (HsWildCardBndrs name thing)
 
+-- | Located Haskell Signature Type
 type LHsSigType   name = HsImplicitBndrs name (LHsType name)    -- Implicit only
+
+-- | Located Haskell Wildcard Type
 type LHsWcType    name = HsWildCardBndrs name (LHsType name)    -- Wildcard only
+
+-- | Located Haskell Signature Wildcard Type
 type LHsSigWcType name = HsWildCardBndrs name (LHsSigType name) -- Both
 
 -- See Note [Representing type signatures]
@@ -378,6 +397,8 @@ instance OutputableBndr HsIPName where
     pprPrefixOcc n = ppr n
 
 --------------------------------------------------
+
+-- | Haskell Type Variable Binder
 data HsTyVarBndr name
   = UserTyVar        -- no explicit kinding
          (Located name)
@@ -401,6 +422,7 @@ isHsKindedTyVar (KindedTyVar {}) = True
 hsTvbAllKinded :: LHsQTyVars name -> Bool
 hsTvbAllKinded = all (isHsKindedTyVar . unLoc) . hsQTvExplicit
 
+-- | Haskell Type
 data HsType name
   = HsForAllTy   -- See Note [HsType binders]
       { hst_bndrs :: [LHsTyVarBndr name]   -- Explicit, user-supplied 'forall a b c'
@@ -566,6 +588,7 @@ deriving instance (DataId name) => Data (HsType name)
 
 -- Note [Literal source text] in BasicTypes for SourceText fields in
 -- the following
+-- | Haskell Type Literal
 data HsTyLit
   = HsNumTy SourceText Integer
   | HsStrTy SourceText FastString
@@ -577,9 +600,11 @@ newtype HsWildCardInfo name      -- See Note [The wildcard story for types]
       -- each individual anonymous wildcard during renaming
 deriving instance (DataId name) => Data (HsWildCardInfo name)
 
+-- | Located Haskell Application Type
 type LHsAppType name = Located (HsAppType name)
       -- ^ 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnSimpleQuote'
 
+-- | Haskell Application Type
 data HsAppType name
   = HsAppInfix (Located name)       -- either a symbol or an id in backticks
   | HsAppPrefix (LHsType name)      -- anything else, including things like (+)
@@ -695,17 +720,22 @@ four constructors of HsTupleSort:
                                         disappears after type checking
 -}
 
+-- | Haskell Tuple Sort
 data HsTupleSort = HsUnboxedTuple
                  | HsBoxedTuple
                  | HsConstraintTuple
                  | HsBoxedOrConstraintTuple
                  deriving Data
 
+
+-- | Located Constructor Declaration Field
 type LConDeclField name = Located (ConDeclField name)
       -- ^ May have 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnComma' when
       --   in a list
 
       -- For details on above see note [Api annotations] in ApiAnnotation
+
+-- | Constructor Declaration Field
 data ConDeclField name  -- Record fields have Haddoc docs on them
   = ConDeclField { cd_fld_names :: [LFieldOcc name],
                                    -- ^ See Note [ConDeclField names]
@@ -721,6 +751,7 @@ instance (OutputableBndrId name) => Outputable (ConDeclField name) where
 
 -- HsConDetails is used for patterns/expressions *and* for data type
 -- declarations
+-- | Haskell Constructor Details
 data HsConDetails arg rec
   = PrefixCon [arg]             -- C p1 p2 p3
   | RecCon    rec               -- C { x = p1, y = p2 }
@@ -1034,9 +1065,12 @@ getLHsInstDeclClass_maybe inst_ty
 ************************************************************************
 -}
 
+-- | Located Field Occurrence
 type LFieldOcc name = Located (FieldOcc name)
 
--- | Represents an *occurrence* of an unambiguous field.  We store
+-- | Field Occurrence
+--
+-- Represents an *occurrence* of an unambiguous field.  We store
 -- both the 'RdrName' the user originally wrote, and after the
 -- renamer, the selector function.
 data FieldOcc name = FieldOcc { rdrNameFieldOcc  :: Located RdrName
@@ -1054,7 +1088,9 @@ mkFieldOcc :: Located RdrName -> FieldOcc RdrName
 mkFieldOcc rdr = FieldOcc rdr PlaceHolder
 
 
--- | Represents an *occurrence* of a field that is potentially
+-- | Ambiguous Field Occurrence
+--
+-- Represents an *occurrence* of a field that is potentially
 -- ambiguous after the renamer, with the ambiguity resolved by the
 -- typechecker.  We always store the 'RdrName' that the user
 -- originally wrote, and store the selector function after the renamer