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

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]
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment