Commit c7dd6da7 authored by Takenobu Tani's avatar Takenobu Tani Committed by Marge Bot

Clean up haddock hyperlinks of GHC.* (part1)

This updates haddock comments only.

This patch focuses to update for hyperlinks in GHC API's haddock comments,
because broken links especially discourage newcomers.

This includes the following hierarchies:
  - GHC.Hs.*
  - GHC.Core.*
  - GHC.Stg.*
  - GHC.Cmm.*
  - GHC.Types.*
  - GHC.Data.*
  - GHC.Builtin.*
  - GHC.Parser.*
  - GHC.Driver.*
  - GHC top
parent 90f43872
......@@ -1010,7 +1010,7 @@ desugarModule tcm = do
--
-- A module must be loaded before dependent modules can be typechecked. This
-- always includes generating a 'ModIface' and, depending on the
-- 'DynFlags.hscTarget', may also include code generation.
-- @DynFlags@\'s 'GHC.Driver.Session.hscTarget', may also include code generation.
--
-- This function will always cause recompilation and will always overwrite
-- previous compilation results (potentially files on disk).
......@@ -1145,7 +1145,7 @@ compileCore simplify fn = do
getModuleGraph :: GhcMonad m => m ModuleGraph -- ToDo: DiGraph ModSummary
getModuleGraph = liftM hsc_mod_graph getSession
-- | Return @True@ <==> module is loaded.
-- | Return @True@ \<==> module is loaded.
isLoaded :: GhcMonad m => ModuleName -> m Bool
isLoaded m = withSession $ \hsc_env ->
return $! isJust (lookupHpt (hsc_HPT hsc_env) m)
......
......@@ -10,7 +10,7 @@ Wired-in knowledge about {\em non-primitive} types
{-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-}
-- | This module is about types that can be defined in Haskell, but which
-- must be wired into the compiler nonetheless. C.f module GHC.Builtin.Types.Prim
-- must be wired into the compiler nonetheless. C.f module "GHC.Builtin.Types.Prim"
module GHC.Builtin.Types (
-- * Helper functions defined here
mkWiredInTyConName, -- This is used in GHC.Builtin.Types.Literals to define the
......@@ -1755,7 +1755,7 @@ mkTupleTy boxity tys = mkTupleTy1 boxity tys
-- | Make a tuple type. The list of types should /not/ include any
-- RuntimeRep specifications. Boxed 1-tuples are *not* flattened.
-- See Note [One-tuples] and Note [Don't flatten tuples from HsSyn]
-- in GHC.Core.Make
-- in "GHC.Core.Make"
mkTupleTy1 :: Boxity -> [Type] -> Type
mkTupleTy1 Boxed tys = mkTyConApp (tupleTyCon Boxed (length tys)) tys
mkTupleTy1 Unboxed tys = mkTyConApp (tupleTyCon Unboxed (length tys))
......
......@@ -9,7 +9,7 @@ Wired-in knowledge about primitive types
{-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-}
-- | This module defines TyCons that can't be expressed in Haskell.
-- They are all, therefore, wired-in TyCons. C.f module GHC.Builtin.Types
-- They are all, therefore, wired-in TyCons. C.f module "GHC.Builtin.Types"
module GHC.Builtin.Types.Prim(
mkPrimTyConName, -- For implicit parameters in GHC.Builtin.Types only
......@@ -138,7 +138,7 @@ import Data.Char
primTyCons :: [TyCon]
primTyCons = unexposedPrimTyCons ++ exposedPrimTyCons
-- | Primitive 'TyCon's that are defined in "GHC.Prim" but not exposed.
-- | Primitive 'TyCon's that are defined in GHC.Prim but not exposed.
-- It's important to keep these separate as we don't want users to be able to
-- write them (see #15209) or see them in GHCi's @:browse@ output
-- (see #12023).
......@@ -149,7 +149,7 @@ unexposedPrimTyCons
, eqPhantPrimTyCon
]
-- | Primitive 'TyCon's that are defined in, and exported from, "GHC.Prim".
-- | Primitive 'TyCon's that are defined in, and exported from, GHC.Prim.
exposedPrimTyCons :: [TyCon]
exposedPrimTyCons
= [ addrPrimTyCon
......
......@@ -111,7 +111,7 @@ Note [About wired-in things]
-- | This list is used to ensure that when you say "Prelude.map" in your source
-- code, or in an interface file, you get a Name with the correct known key (See
-- Note [Known-key names] in GHC.Builtin.Names)
-- Note [Known-key names] in "GHC.Builtin.Names")
knownKeyNames :: [Name]
knownKeyNames
| debugIsOn
......
......@@ -164,7 +164,7 @@ import GHC.CmmToAsm.Config
- By the C-- AST to identify labels
- By the unregisterised C code generator ("PprC") for naming functions (hence
- By the unregisterised C code generator (\"PprC\") for naming functions (hence
the name 'CLabel')
- By the native and LLVM code generators to identify labels
......
......@@ -46,7 +46,7 @@ import GHC.Prelude
-- | Used at the type level to indicate "open" vs "closed" structure.
data Extensibility
-- | An "open" structure with a unique, unnamed control-flow edge flowing in
-- or out. "Fallthrough" and concatenation are permitted at an open point.
-- or out. \"Fallthrough\" and concatenation are permitted at an open point.
= Open
-- | A "closed" structure which supports control transfer only through the use
-- of named labels---no "fallthrough" is permitted. The number of control-flow
......
......@@ -281,7 +281,7 @@ mkSRTLit platform _ (Just lbl) = ([CmmLabel lbl], CmmInt 1 (halfWordWidth platfo
-- | Is the SRT offset field inline in the info table on this platform?
--
-- See the section "Referring to an SRT from the info table" in
-- Note [SRTs] in GHC.Cmm.Info.Build
-- Note [SRTs] in "GHC.Cmm.Info.Build"
inlineSRT :: Platform -> Bool
inlineSRT platform = platformArch platform == ArchX86_64
&& platformTablesNextToCode platform
......
......@@ -144,10 +144,10 @@ These data types are the heart of the compiler
-- We get from Haskell source to this Core language in a number of stages:
--
-- 1. The source code is parsed into an abstract syntax tree, which is represented
-- by the data type 'GHC.Hs.Expr.HsExpr' with the names being 'RdrName.RdrNames'
-- by the data type 'GHC.Hs.Expr.HsExpr' with the names being 'GHC.Types.Name.Reader.RdrNames'
--
-- 2. This syntax tree is /renamed/, which attaches a 'Unique.Unique' to every 'RdrName.RdrName'
-- (yielding a 'Name.Name') to disambiguate identifiers which are lexically identical.
-- 2. This syntax tree is /renamed/, which attaches a 'GHC.Types.Unique.Unique' to every 'GHC.Types.Name.Reader.RdrName'
-- (yielding a 'GHC.Types.Name.Name') to disambiguate identifiers which are lexically identical.
-- For example, this program:
--
-- @
......@@ -164,7 +164,7 @@ These data types are the heart of the compiler
-- But see Note [Shadowing] below.
--
-- 3. The resulting syntax tree undergoes type checking (which also deals with instantiating
-- type class arguments) to yield a 'GHC.Hs.Expr.HsExpr' type that has 'Id.Id' as it's names.
-- type class arguments) to yield a 'GHC.Hs.Expr.HsExpr' type that has 'GHC.Types.Id.Id' as it's names.
--
-- 4. Finally the syntax tree is /desugared/ from the expressive 'GHC.Hs.Expr.HsExpr' type into
-- this 'Expr' type, which has far fewer constructors and hence is easier to perform
......@@ -965,10 +965,10 @@ data Tickish id =
{ breakpointId :: !Int
, breakpointFVs :: [id] -- ^ the order of this list is important:
-- it matches the order of the lists in the
-- appropriate entry in GHC.Driver.Types.ModBreaks.
-- appropriate entry in 'GHC.Driver.Types.ModBreaks'.
--
-- Careful about substitution! See
-- Note [substTickish] in GHC.Core.Subst.
-- Note [substTickish] in "GHC.Core.Subst".
}
-- | A source note.
......@@ -1338,7 +1338,7 @@ data CoreRule
-- Rough-matching stuff
-- see comments with InstEnv.ClsInst( is_cls, is_rough )
ru_fn :: Name, -- ^ Name of the 'Id.Id' at the head of this rule
ru_fn :: Name, -- ^ Name of the 'GHC.Types.Id.Id' at the head of this rule
ru_rough :: [Maybe Name], -- ^ Name at the head of each argument to the left hand side
-- Proper-matching stuff
......@@ -1355,7 +1355,7 @@ data CoreRule
ru_auto :: Bool, -- ^ @True@ <=> this rule is auto-generated
-- (notably by Specialise or SpecConstr)
-- @False@ <=> generated at the user's behest
-- See Note [Trimming auto-rules] in GHC.Iface.Tidy
-- See Note [Trimming auto-rules] in "GHC.Iface.Tidy"
-- for the sole purpose of this field.
ru_origin :: !Module, -- ^ 'Module' the rule was defined in, used
......@@ -1429,14 +1429,14 @@ ruleActivation :: CoreRule -> Activation
ruleActivation (BuiltinRule { }) = AlwaysActive
ruleActivation (Rule { ru_act = act }) = act
-- | The 'Name' of the 'Id.Id' at the head of the rule left hand side
-- | The 'Name' of the 'GHC.Types.Id.Id' at the head of the rule left hand side
ruleIdName :: CoreRule -> Name
ruleIdName = ru_fn
isLocalRule :: CoreRule -> Bool
isLocalRule = ru_local
-- | Set the 'Name' of the 'Id.Id' at the head of the rule left hand side
-- | Set the 'Name' of the 'GHC.Types.Id.Id' at the head of the rule left hand side
setRuleIdName :: Name -> CoreRule -> CoreRule
setRuleIdName nm ru = ru { ru_fn = nm }
......@@ -1452,13 +1452,13 @@ The @Unfolding@ type is declared here to avoid numerous loops
-- | Records the /unfolding/ of an identifier, which is approximately the form the
-- identifier would have if we substituted its definition in for the identifier.
-- This type should be treated as abstract everywhere except in GHC.Core.Unfold
-- This type should be treated as abstract everywhere except in "GHC.Core.Unfold"
data Unfolding
= NoUnfolding -- ^ We have no information about the unfolding.
| BootUnfolding -- ^ We have no information about the unfolding, because
-- this 'Id' came from an @hi-boot@ file.
-- See Note [Inlining and hs-boot files] in GHC.CoreToIface
-- See Note [Inlining and hs-boot files] in "GHC.CoreToIface"
-- for what this is used for.
| OtherCon [AltCon] -- ^ It ain't one of these constructors.
......
......@@ -77,7 +77,7 @@ data Class
--
-- Here fun-deps are [([a,b],[c]), ([a,c],[b])]
--
-- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnRarrow'',
-- - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnRarrow'',
-- For details on above see note [Api annotations] in GHC.Parser.Annotation
type FunDep a = ([a],[a])
......
......@@ -2445,7 +2445,7 @@ mkReprPrimEqPred ty1 ty2
-- a nominal coercion between the types. This is useful when optimizing
-- transitivity over coercion applications, where splitting two
-- AppCos might yield different kinds. See Note [EtaAppCo] in
-- GHC.Core.Coercion.Opt.
-- "GHC.Core.Coercion.Opt".
buildCoercion :: Type -> Type -> CoercionN
buildCoercion orig_ty1 orig_ty2 = go orig_ty1 orig_ty2
where
......@@ -2956,11 +2956,11 @@ bad_co_hole_co :: Coercion -> Monoid.Any
hole _ = Monoid.Any False
-- | Is there a blocking coercion hole in this type? See
-- TcCanonical Note [Equalities with incompatible kinds]
-- "GHC.Tc.Solver.Canonical" Note [Equalities with incompatible kinds]
badCoercionHole :: Type -> Bool
badCoercionHole = Monoid.getAny . bad_co_hole_ty
-- | Is there a blocking coercion hole in this coercion? See
-- TcCanonical Note [Equalities with incompatible kinds]
-- GHC.Tc.Solver.Canonical Note [Equalities with incompatible kinds]
badCoercionHoleCo :: Coercion -> Bool
badCoercionHoleCo = Monoid.getAny . bad_co_hole_co
......@@ -302,8 +302,8 @@ Note that (Foo a) might not be an instance of Ord.
-- | A data constructor
--
-- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen',
-- 'ApiAnnotation.AnnClose','ApiAnnotation.AnnComma'
-- - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnOpen',
-- 'GHC.Parser.Annotation.AnnClose','GHC.Parser.Annotation.AnnComma'
-- For details on above see note [Api annotations] in GHC.Parser.Annotation
data DataCon
......@@ -953,7 +953,7 @@ mkDataCon :: Name
-> KnotTied ThetaType -- ^ Theta-type occurring before the arguments proper
-> [KnotTied (Scaled Type)] -- ^ Original argument types
-> KnotTied Type -- ^ Original result type
-> RuntimeRepInfo -- ^ See comments on 'TyCon.RuntimeRepInfo'
-> RuntimeRepInfo -- ^ See comments on 'GHC.Core.TyCon.RuntimeRepInfo'
-> KnotTied TyCon -- ^ Representation type constructor
-> ConTag -- ^ Constructor tag
-> ThetaType -- ^ The "stupid theta", context of the data
......
......@@ -106,7 +106,7 @@ exprFreeVars :: CoreExpr -> VarSet
exprFreeVars = fvVarSet . exprFVs
-- | Find all locally-defined free Ids or type variables in an expression
-- returning a composable FV computation. See Note [FV naming conventions] in GHC.Utils.FV
-- returning a composable FV computation. See Note [FV naming conventions] in "GHC.Utils.FV"
-- for why export it.
exprFVs :: CoreExpr -> FV
exprFVs = filterFV isLocalVar . expr_fvs
......@@ -151,7 +151,7 @@ exprsFreeVars :: [CoreExpr] -> VarSet
exprsFreeVars = fvVarSet . exprsFVs
-- | Find all locally-defined free Ids or type variables in several expressions
-- returning a composable FV computation. See Note [FV naming conventions] in GHC.Utils.FV
-- returning a composable FV computation. See Note [FV naming conventions] in "GHC.Utils.FV"
-- for why export it.
exprsFVs :: [CoreExpr] -> FV
exprsFVs exprs = mapUnionFV exprFVs exprs
......
......@@ -453,7 +453,7 @@ classInstances (InstEnvs { ie_global = pkg_ie, ie_local = home_ie, ie_visible =
Nothing -> []
-- | Checks for an exact match of ClsInst in the instance environment.
-- We use this when we do signature checking in GHC.Tc.Module
-- We use this when we do signature checking in "GHC.Tc.Module"
memberInstEnv :: InstEnv -> ClsInst -> Bool
memberInstEnv inst_env ins_item@(ClsInst { is_cls_nm = cls_nm } ) =
maybe False (\(ClsIE items) -> any (identicalDFunType ins_item) items)
......@@ -835,8 +835,8 @@ lookupInstEnv :: Bool -- Check Safe Haskell overlap restrictions
-> Class -> [Type] -- What we are looking for
-> ClsInstLookupResult
-- ^ See Note [Rules for instance lookup]
-- ^ See Note [Safe Haskell Overlapping Instances] in GHC.Tc.Solver
-- ^ See Note [Safe Haskell Overlapping Instances Implementation] in GHC.Tc.Solver
-- ^ See Note [Safe Haskell Overlapping Instances] in "GHC.Tc.Solver"
-- ^ See Note [Safe Haskell Overlapping Instances Implementation] in "GHC.Tc.Solver"
lookupInstEnv check_overlap_safe
(InstEnvs { ie_global = pkg_ie
, ie_local = home_ie
......
......@@ -722,7 +722,7 @@ lintRhs _bndr rhs = fmap lf_check_static_ptrs getLintFlags >>= go
go _ = markAllJoinsBad $ lintCoreExpr rhs
-- | Lint the RHS of a join point with expected join arity of @n@ (see Note
-- [Join points] in GHC.Core).
-- [Join points] in "GHC.Core").
lintJoinLams :: JoinArity -> Maybe Id -> CoreExpr -> LintM (LintedType, UsageEnv)
lintJoinLams join_arity enforce rhs
= go join_arity rhs
......
......@@ -135,7 +135,7 @@ mkCoreConApps con args = mkCoreApps (Var (dataConWorkId con)) args
-- | Construct an expression which represents the application of a number of
-- expressions to another. The leftmost expression in the list is applied first
-- Respects the let/app invariant by building a case expression where necessary
-- See Note [Core let/app invariant] in GHC.Core
-- See Note [Core let/app invariant] in "GHC.Core"
mkCoreApps :: CoreExpr -> [CoreExpr] -> CoreExpr
mkCoreApps fun args
= fst $
......@@ -147,7 +147,7 @@ mkCoreApps fun args
-- | Construct an expression which represents the application of one expression
-- to the other
-- Respects the let/app invariant by building a case expression where necessary
-- See Note [Core let/app invariant] in GHC.Core
-- See Note [Core let/app invariant] in "GHC.Core"
mkCoreApp :: SDoc -> CoreExpr -> CoreExpr -> CoreExpr
mkCoreApp s fun arg
= fst $ mkCoreAppTyped s (fun, exprType fun) arg
......@@ -157,7 +157,7 @@ mkCoreApp s fun arg
-- function is not exported and used in the definition of 'mkCoreApp' and
-- 'mkCoreApps'.
-- Respects the let/app invariant by building a case expression where necessary
-- See Note [Core let/app invariant] in GHC.Core
-- See Note [Core let/app invariant] in "GHC.Core"
mkCoreAppTyped :: SDoc -> (CoreExpr, Type) -> CoreExpr -> (CoreExpr, Type)
mkCoreAppTyped _ (fun, fun_ty) (Type ty)
= (App fun (Type ty), piResultTy fun_ty ty)
......@@ -193,7 +193,7 @@ mkWildEvBinder pred = mkWildValBinder Many pred
-- that you expect to use only at a *binding* site. Do not use it at
-- occurrence sites because it has a single, fixed unique, and it's very
-- easy to get into difficulties with shadowing. That's why it is used so little.
-- See Note [WildCard binders] in GHC.Core.Opt.Simplify.Env
-- See Note [WildCard binders] in "GHC.Core.Opt.Simplify.Env"
mkWildValBinder :: Mult -> Type -> Id
mkWildValBinder w ty = mkLocalIdOrCoVar wildCardName w ty
-- "OrCoVar" since a coercion can be a scrutinee with -fdefer-type-errors
......
......@@ -481,7 +481,7 @@ data TypeMapX a
-- Note that there is no tyconapp case; see Note [Equality on AppTys] in GHC.Core.Type
-- | Squeeze out any synonyms, and change TyConApps to nested AppTys. Why the
-- last one? See Note [Equality on AppTys] in GHC.Core.Type
-- last one? See Note [Equality on AppTys] in "GHC.Core.Type"
--
-- Note, however, that we keep Constraint and Type apart here, despite the fact
-- that they are both synonyms of TYPE 'LiftedRep (see #11715).
......
......@@ -2850,7 +2850,7 @@ setBinderOcc occ_info bndr
-- the decision about another binding 'g' might be invalidated if (say)
-- 'f' tail-calls 'g'.
--
-- See Note [Invariants on join points] in GHC.Core.
-- See Note [Invariants on join points] in "GHC.Core".
decideJoinPointHood :: TopLevelFlag -> UsageDetails
-> [CoreBndr]
-> Bool
......
......@@ -202,7 +202,7 @@ roughTopNames :: [CoreExpr] -> [Maybe Name]
-- Such names are either:
--
-- 1. The function finally being applied to in an application chain
-- (if that name is a GlobalId: see "Var#globalvslocal"), or
-- (if that name is a GlobalId: see "GHC.Types.Var#globalvslocal"), or
--
-- 2. The 'TyCon' if the expression is a 'Type'
--
......
......@@ -1060,7 +1060,7 @@ data ConCont = CC [CoreExpr] Coercion
-- [exprIsConApp_maybe on data constructors with wrappers]. Data constructor wrappers
-- are unfolded late, but we really want to trigger case-of-known-constructor as
-- early as possible. See also Note [Activation for data constructor wrappers]
-- in GHC.Types.Id.Make.
-- in "GHC.Types.Id.Make".
--
-- We also return the incoming InScopeSet, augmented with
-- the binders from any [FloatBind] that we return
......
......@@ -80,9 +80,9 @@ import Data.List
--
-- Some invariants apply to how you use the substitution:
--
-- 1. Note [The substitution invariant] in GHC.Core.TyCo.Subst
-- 1. Note [The substitution invariant] in "GHC.Core.TyCo.Subst"
--
-- 2. Note [Substitutions apply only once] in GHC.Core.TyCo.Subst
-- 2. Note [Substitutions apply only once] in "GHC.Core.TyCo.Subst"
data Subst
= Subst InScopeSet -- Variables in in scope (both Ids and TyVars) /after/
-- applying the substitution
......@@ -172,7 +172,7 @@ mkEmptySubst in_scope = Subst in_scope emptyVarEnv emptyVarEnv emptyVarEnv
mkSubst :: InScopeSet -> TvSubstEnv -> CvSubstEnv -> IdSubstEnv -> Subst
mkSubst in_scope tvs cvs ids = Subst in_scope ids tvs cvs
-- | Find the in-scope set: see TyCoSubst Note [The substitution invariant]
-- | Find the in-scope set: see "GHC.Core.TyCo.Subst" Note [The substitution invariant]
substInScope :: Subst -> InScopeSet
substInScope (Subst in_scope _ _ _) = in_scope
......@@ -199,7 +199,7 @@ extendIdSubstList (Subst in_scope ids tvs cvs) prs
-- | Add a substitution for a 'TyVar' to the 'Subst'
-- The 'TyVar' *must* be a real TyVar, and not a CoVar
-- You must ensure that the in-scope set is such that
-- TyCoSubst Note [The substitution invariant] holds
-- "GHC.Core.TyCo.Subst" Note [The substitution invariant] holds
-- after extending the substitution like this.
extendTvSubst :: Subst -> TyVar -> Type -> Subst
extendTvSubst (Subst in_scope ids tvs cvs) tv ty
......@@ -215,7 +215,7 @@ extendTvSubstList subst vrs
-- | Add a substitution from a 'CoVar' to a 'Coercion' to the 'Subst':
-- you must ensure that the in-scope set satisfies
-- TyCoSubst Note [The substitution invariant]
-- "GHC.Core.TyCo.Subst" Note [The substitution invariant]
-- after extending the substitution like this
extendCvSubst :: Subst -> CoVar -> Coercion -> Subst
extendCvSubst (Subst in_scope ids tvs cvs) v r
......@@ -340,7 +340,7 @@ instance Outputable Subst where
-- | Apply a substitution to an entire 'CoreExpr'. Remember, you may only
-- apply the substitution /once/:
-- See Note [Substitutions apply only once] in GHC.Core.TyCo.Subst
-- See Note [Substitutions apply only once] in "GHC.Core.TyCo.Subst"
--
-- Do *not* attempt to short-cut in the case of an empty substitution!
-- See Note [Extending the Subst]
......
......@@ -523,14 +523,14 @@ closeOverKindsDSet = fvDVarSet . closeOverKindsFV . dVarSetElems
-- | `tyCoFVsOfType` that returns free variables of a type in a deterministic
-- set. For explanation of why using `VarSet` is not deterministic see
-- Note [Deterministic FV] in GHC.Utils.FV.
-- Note [Deterministic FV] in "GHC.Utils.FV".
tyCoVarsOfTypeDSet :: Type -> DTyCoVarSet
-- See Note [Free variables of types]
tyCoVarsOfTypeDSet ty = fvDVarSet $ tyCoFVsOfType ty
-- | `tyCoFVsOfType` that returns free variables of a type in deterministic
-- order. For explanation of why using `VarSet` is not deterministic see
-- Note [Deterministic FV] in GHC.Utils.FV.
-- Note [Deterministic FV] in "GHC.Utils.FV".
tyCoVarsOfTypeList :: Type -> [TyCoVar]
-- See Note [Free variables of types]
tyCoVarsOfTypeList ty = fvVarList $ tyCoFVsOfType ty
......@@ -554,10 +554,10 @@ tyCoVarsOfTypesList tys = fvVarList $ tyCoFVsOfTypes tys
-- make the function quadratic.
-- It's exported, so that it can be composed with
-- other functions that compute free variables.
-- See Note [FV naming conventions] in GHC.Utils.FV.
-- See Note [FV naming conventions] in "GHC.Utils.FV".
--
-- Eta-expanded because that makes it run faster (apparently)
-- See Note [FV eta expansion] in GHC.Utils.FV for explanation.
-- See Note [FV eta expansion] in "GHC.Utils.FV" for explanation.
tyCoFVsOfType :: Type -> FV
-- See Note [Free variables of types]
tyCoFVsOfType (TyVarTy v) f bound_vars (acc_list, acc_set)
......@@ -655,7 +655,7 @@ tyCoFVsOfCos (co:cos) fv_cand in_scope acc = (tyCoFVsOfCo co `unionFV` tyCoFVsOf
-- | Given a covar and a coercion, returns True if covar is almost devoid in
-- the coercion. That is, covar can only appear in Refl and GRefl.
-- See last wrinkle in Note [Unused coercion variable in ForAllCo] in GHC.Core.Coercion
-- See last wrinkle in Note [Unused coercion variable in ForAllCo] in "GHC.Core.Coercion"
almostDevoidCoVarOfCo :: CoVar -> Coercion -> Bool
almostDevoidCoVarOfCo cv co =
almost_devoid_co_var_of_co co cv
......@@ -777,7 +777,7 @@ almost_devoid_co_var_of_types (ty:tys) cv
-- See @Note [When does a tycon application need an explicit kind signature?]@.
injectiveVarsOfType :: Bool -- ^ Should we look under injective type families?
-- See Note [Coverage condition for injective type families]
-- in GHC.Tc.Instance.Family.
-- in "GHC.Tc.Instance.Family".
-> Type -> FV
injectiveVarsOfType look_under_tfs = go
where
......@@ -812,7 +812,7 @@ injectiveVarsOfType look_under_tfs = go
-- See @Note [When does a tycon application need an explicit kind signature?]@.
injectiveVarsOfTypes :: Bool -- ^ look under injective type families?
-- See Note [Coverage condition for injective type families]
-- in GHC.Tc.Instance.Family.
-- in "GHC.Tc.Instance.Family".
-> [Type] -> FV
injectiveVarsOfTypes look_under_tfs = mapUnionFV (injectiveVarsOfType look_under_tfs)
......@@ -831,7 +831,7 @@ injectiveVarsOfTypes look_under_tfs = mapUnionFV (injectiveVarsOfType look_under
-- * In the kind of a bound variable in a forall
-- * In a coercion
-- * In a Specified or Inferred argument to a function
-- See Note [VarBndrs, TyCoVarBinders, TyConBinders, and visibility] in GHC.Core.TyCo.Rep
-- See Note [VarBndrs, TyCoVarBinders, TyConBinders, and visibility] in "GHC.Core.TyCo.Rep"
invisibleVarsOfType :: Type -> FV
invisibleVarsOfType = go
where
......@@ -935,7 +935,7 @@ types/kinds are fully settled and zonked.
--
-- It is also meant to be stable: that is, variables should not
-- be reordered unnecessarily. This is specified in Note [ScopedSort]
-- See also Note [Ordering of implicit variables] in GHC.Rename.HsType
-- See also Note [Ordering of implicit variables] in "GHC.Rename.HsType"
scopedSort :: [TyCoVar] -> [TyCoVar]
scopedSort = go [] []
......
......@@ -304,7 +304,7 @@ pprTypeApp tc tys
------------------
-- | Display all kind information (with @-fprint-explicit-kinds@) when the
-- provided 'Bool' argument is 'True'.
-- See @Note [Kind arguments in error messages]@ in GHC.Tc.Errors.
-- See @Note [Kind arguments in error messages]@ in "GHC.Tc.Errors".
pprWithExplicitKindsWhen :: Bool -> SDoc -> SDoc
pprWithExplicitKindsWhen b
= updSDocContext $ \ctx ->
......
......@@ -129,7 +129,7 @@ The Class and its associated TyCon have the same Name.
-- | A global typecheckable-thing, essentially anything that has a name.
-- Not to be confused with a 'TcTyThing', which is also a typecheckable
-- thing but in the *local* context. See 'GHC.Tc.Utils.Env' for how to retrieve
-- thing but in the *local* context. See "GHC.Tc.Utils.Env" for how to retrieve
-- a 'TyThing' given a 'Name'.
data TyThing
= AnId Id
......@@ -189,7 +189,7 @@ data Type
--
-- 1) Function: must /not/ be a 'TyConApp' or 'CastTy',
-- must be another 'AppTy', or 'TyVarTy'
-- See Note [Respecting definitional equality] (EQ1) about the
-- See Note [Respecting definitional equality] \(EQ1) about the
-- no 'CastTy' requirement
--
-- 2) Argument type
......@@ -233,7 +233,7 @@ data Type
-- INVARIANT: The cast is never reflexive
-- INVARIANT: The Type is not a CastTy (use TransCo instead)
-- INVARIANT: The Type is not a ForAllTy over a type variable
-- See Note [Respecting definitional equality] (EQ2), (EQ3), (EQ4)
-- See Note [Respecting definitional equality] \(EQ2), (EQ3), (EQ4)
| CoercionTy
Coercion -- ^ Injection of a Coercion into a type
......@@ -675,7 +675,7 @@ are truly unrelated.
-- | A type labeled 'KnotTied' might have knot-tied tycons in it. See
-- Note [Type checking recursive type and class declarations] in
-- GHC.Tc.TyCl
-- "GHC.Tc.TyCl"
type KnotTied ty = ty
{- **********************************************************************
......@@ -1886,7 +1886,7 @@ data TyCoFolder env a
, tcf_covar :: env -> CoVar -> a
, tcf_hole :: env -> CoercionHole -> a
-- ^ What to do with coercion holes.
-- See Note [Coercion holes] in GHC.Core.TyCo.Rep.
-- See Note [Coercion holes] in "GHC.Core.TyCo.Rep".
, tcf_tycobinder :: env -> TyCoVar -> ArgFlag -> env
-- ^ The returned env is used in the extended scope
......
......@@ -900,7 +900,7 @@ data TyCon
}
-- | These exist only during type-checking. See Note [How TcTyCons work]
-- in GHC.Tc.TyCl
-- in "GHC.Tc.TyCl"
| TcTyCon {
tyConUnique :: Unique,
tyConName :: Name,
......@@ -1043,7 +1043,7 @@ mkDataTyConRhs cons
-- constructor of 'PrimRep'. This data structure allows us to store this
-- information right in the 'TyCon'. The other approach would be to look
-- up things like @RuntimeRep@'s @PrimRep@ by known-key every time.
-- See also Note [Getting from RuntimeRep to PrimRep] in GHC.Types.RepType
-- See also Note [Getting from RuntimeRep to PrimRep] in "GHC.Types.RepType"
data RuntimeRepInfo
= NoRRI -- ^ an ordinary promoted data con
| RuntimeRep ([Type] -> [PrimRep])
......@@ -1078,7 +1078,7 @@ data AlgTyConFlav
(Maybe TyConRepName)
-- | Type constructors representing a class dictionary.
-- See Note [ATyCon for classes] in GHC.Core.TyCo.Rep
-- See Note [ATyCon for classes] in "GHC.Core.TyCo.Rep"
| ClassTyCon
Class -- INVARIANT: the classTyCon of this Class is the
-- current tycon
......@@ -1334,7 +1334,7 @@ tyConRepName_maybe _ = Nothing
-- | Make a 'Name' for the 'Typeable' representation of the given wired-in type
mkPrelTyConRepName :: Name -> TyConRepName
-- See Note [Grand plan for Typeable] in 'GHC.Tc.Instance.Typeable'.
-- See Note [Grand plan for Typeable] in "GHC.Tc.Instance.Typeable".
mkPrelTyConRepName tc_name -- Prelude tc_name is always External,
-- so nameModule will work
= mkExternalName rep_uniq rep_mod rep_occ (nameSrcSpan tc_name)
......@@ -1349,7 +1349,7 @@ mkPrelTyConRepName tc_name -- Prelude tc_name is always External,
-- | The name (and defining module) for the Typeable representation (TyCon) of a
-- type constructor.
--
-- See Note [Grand plan for Typeable] in 'GHC.Tc.Instance.Typeable'.
-- See Note [Grand plan for Typeable] in "GHC.Tc.Instance.Typeable".
tyConRepModOcc :: Module -> OccName -> (Module, OccName)
tyConRepModOcc tc_module tc_occ = (rep_module, mkTyConRepOcc tc_occ)
where
......@@ -1428,7 +1428,7 @@ See Note [RuntimeRep and PrimRep] in GHC.Types.RepType.
-- | A 'PrimRep' is an abstraction of a type. It contains information that
-- the code generator needs in order to pass arguments, return results,
-- and store values of this type. See also Note [RuntimeRep and PrimRep] in
-- GHC.Types.RepType and Note [VoidRep] in GHC.Types.RepType.
-- "GHC.Types.RepType" and Note [VoidRep] in "GHC.Types.RepType".
data PrimRep
= VoidRep
| LiftedRep
......@@ -1705,7 +1705,7 @@ mkSumTyCon name binders res_kind arity tyvars cons parent
-- mutually-recursive group of tycons; it is then zonked to a proper
-- TyCon in zonkTcTyCon.
-- See also Note [Kind checking recursive type and class declarations]
-- in GHC.Tc.TyCl.
-- in "GHC.Tc.TyCl".
mkTcTyCon :: Name
-> [TyConBinder]
-> Kind -- ^ /result/ kind only
......@@ -1907,7 +1907,7 @@ isDataTyCon _ = False
-- (where X is the role passed in):
-- If (T a1 b1 c1) ~X (T a2 b2 c2), then (a1 ~X1 a2), (b1 ~X2 b2), and (c1 ~X3 c2)
-- (where X1, X2, and X3, are the roles given by tyConRolesX tc X)
-- See also Note [Decomposing equality] in GHC.Tc.Solver.Canonical
-- See also Note [Decomposing equality] in "GHC.Tc.Solver.Canonical"
isInjectiveTyCon :: TyCon -> Role -> Bool
isInjectiveTyCon _ Phantom = False
isInjectiveTyCon (FunTyCon {}) _ = True
......@@ -1928,7 +1928,7 @@ isInjectiveTyCon (TcTyCon {}) _ = True
-- | 'isGenerativeTyCon' is true of 'TyCon's for which this property holds
-- (where X is the role passed in):
-- If (T tys ~X t), then (t's head ~X T).
-- See also Note [Decomposing equality] in GHC.Tc.Solver.Canonical
-- See also Note [Decomposing equality] in "GHC.Tc.Solver.Canonical"
isGenerativeTyCon :: TyCon -> Role -> Bool
isGenerativeTyCon (FamilyTyCon { famTcFlav = DataFamilyTyCon _ }) Nominal = True
isGenerativeTyCon (FamilyTyCon {}) _ = False
......
......@@ -660,7 +660,7 @@ data TyCoMapper env m
, tcm_covar :: env -> CoVar -> m Coercion
, tcm_hole :: env -> CoercionHole -> m Coercion
-- ^ What to do with coercion holes.
-- See Note [Coercion holes] in GHC.Core.TyCo.Rep.
-- See Note [Coercion holes] in "GHC.Core.TyCo.Rep".
, tcm_tycobinder :: env -> TyCoVar -> ArgFlag -> m (env, TyCoVar)
-- ^ The returned env is used in the extended scope
......@@ -670,7 +670,7 @@ data TyCoMapper env m
-- a) To zonk TcTyCons
-- b) To turn TcTyCons into TyCons.
-- See Note [Type checking recursive type and class declarations]
-- in GHC.Tc.TyCl
-- in "GHC.Tc.TyCl"
}
{-# INLINE mapTyCo #-} -- See Note [Specialising mappers]
......@@ -1326,7 +1326,7 @@ repSplitTyConApp_maybe :: HasDebugCallStack => Type -> Maybe (TyCon, [Type])
-- have enough info to extract the runtime-rep arguments that
-- the funTyCon requires. This will usually be true;
-- but may be temporarily false during canonicalization:
-- see Note [FunTy and decomposing tycon applications] in GHC.Tc.Solver.Canonical
-- see Note [FunTy and decomposing tycon applications] in "GHC.Tc.Solver.Canonical"
--
repSplitTyConApp_maybe (TyConApp tc tys) = Just (tc, tys)
repSplitTyConApp_maybe (FunTy _ w arg res)
......@@ -1367,7 +1367,7 @@ splitCastTy_maybe ty
-- | Make a 'CastTy'. The Coercion must be nominal. Checks the
-- Coercion for reflexivity, dropping it if it's reflexive.
-- See Note [Respecting definitional equality] in GHC.Core.TyCo.Rep
-- See Note [Respecting definitional equality] in "GHC.Core.TyCo.Rep"
mkCastTy :: Type -> Coercion -> Type
mkCastTy ty co | isReflexiveCo co = ty -- (EQ2) from the Note
-- NB: Do the slow check here. This is important to keep the splitXXX
......@@ -1404,7 +1404,7 @@ tyConBindersTyCoBinders = map to_tyb
-- | Drop the cast on a type, if any. If there is no
-- cast, just return the original type. This is rarely what
-- you want. The CastTy data constructor (in GHC.Core.TyCo.Rep) has the
-- you want. The CastTy data constructor (in "GHC.Core.TyCo.Rep") has the
-- invariant that another CastTy is not inside. See the
-- data constructor for a full description of this invariant.
-- Since CastTy cannot be nested, the result of discardCast
......@@ -1949,7 +1949,7 @@ isFamFreeTy (CoercionTy _) = False -- Not sure about this
-- | Does this type classify a core (unlifted) Coercion?
-- At either role nominal or representational
-- (t1 ~# t2) or (t1 ~R# t2)
-- See Note [Types for coercions, predicates, and evidence] in GHC.Core.TyCo.Rep
-- See Note [Types for coercions, predicates, and evidence] in "GHC.Core.TyCo.Rep"
isCoVarType :: Type -> Bool
-- ToDo: should we check saturation?
isCoVarType ty
......@@ -2091,7 +2091,7 @@ isPrimitiveType ty = case splitTyConApp_maybe ty of
-- in its return type, since given
-- join j @a @b x y z = e1 in e2,
-- the types of e1 and e2 must be the same, and a and b are not in scope for e2.
-- (See Note [The polymorphism rule of join points] in GHC.Core.) Returns False
-- (See Note [The polymorphism rule of join points] in "GHC.Core".) Returns False
-- also if the type simply doesn't have enough arguments.
--
-- Note that we need to know how many arguments (type *and* value) the putative
......@@ -2197,7 +2197,7 @@ eqType :: Type -> Type -> Bool
-- checks whether the types are equal, ignoring casts and coercions.
-- (The kind check is a recursive call, but since all kinds have type
-- @Type@, there is no need to check the types of kinds.)
-- See also Note [Non-trivial definitional equality] in GHC.Core.TyCo.Rep.
-- See also Note [Non-trivial definitional equality] in "GHC.Core.TyCo.Rep".
eqType t1 t2 = isEqual $ nonDetCmpType t1 t2
-- It's OK to use nonDetCmpType here and eqType is deterministic,
-- nonDetCmpType does equality deterministically
......
......@@ -1551,7 +1551,7 @@ it's applied only to dictionaries.
-- exprIsHNF implies exprOkForSpeculation
-- exprOkForSpeculation implies exprOkForSideEffects
--
-- See Note [PrimOp can_fail and has_side_effects] in GHC.Builtin.PrimOps
-- See Note [PrimOp can_fail and has_side_effects] in "GHC.Builtin.PrimOps"
-- and Note [Transformations affected by can_fail and has_side_effects]
--
-- As an example of the considerations in this test, consider:
......@@ -1958,7 +1958,7 @@ exprIsTopLevelBindable :: CoreExpr -> Type -> Bool
-- See Note [Core top-level string literals]
-- Precondition: exprType expr = ty
-- Top-level literal strings can't even be wrapped in ticks
-- see Note [Core top-level string literals] in GHC.Core
-- see Note [Core top-level string literals] in "GHC.Core"
exprIsTopLevelBindable expr ty
= not (mightBeUnliftedType ty)
-- Note that 'expr' may be levity polymorphic here consequently we must use
......
......@@ -12,9 +12,9 @@
-- ['FastString']
--
-- * A compact, hash-consed, representation of character strings.
-- * Comparison is O(1), and you can get a 'Unique.Unique' from them.
-- * Comparison is O(1), and you can get a 'GHC.Types.Unique.Unique' from them.
-- * Generated by 'fsLit'.
-- * Turn into 'Outputable.SDoc' with 'Outputable.ftext'.
-- * Turn into 'GHC.Utils.Outputable.SDoc' with 'GHC.Utils.Outputable.ftext'.
--
-- ['PtrString']
--
......@@ -22,7 +22,7 @@