Commit 1eb997a8 authored by Takenobu Tani's avatar Takenobu Tani Committed by Marge Bot

Clean up haddock hyperlinks of GHC.* (part2)

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.Iface.*
  - GHC.Llvm.*

  - GHC.Rename.*
  - GHC.Tc.*

  - GHC.HsToCore.*
  - GHC.StgToCmm.*
  - GHC.CmmToAsm.*

  - GHC.Runtime.*

  - GHC.Unit.*
  - GHC.Utils.*
  - GHC.SysTools.*
parent c7dd6da7
......@@ -107,7 +107,7 @@ instance Outputable EdgeWeight where
type EdgeInfoMap edgeInfo = LabelMap (LabelMap edgeInfo)
-- | A control flow graph where edges have been annotated with a weight.
-- Implemented as IntMap (IntMap <edgeData>)
-- Implemented as IntMap (IntMap \<edgeData>)
-- We must uphold the invariant that for each edge A -> B we must have:
-- A entry B in the outer map.
-- A entry B in the map we get when looking up A.
......@@ -148,7 +148,7 @@ instance Outputable CfgEdge where
-- | Can we trace back a edge to a specific Cmm Node
-- or has it been introduced during assembly codegen. We use this to maintain
-- some information which would otherwise be lost during the
-- Cmm <-> asm transition.
-- Cmm \<-> asm transition.
-- See also Note [Inverting Conditional Branches]
data TransitionSource
= CmmSource { trans_cmmNode :: (CmmNode O C)
......
-- | Constants describing the DWARF format. Most of this simply
-- mirrors /usr/include/dwarf.h.
-- mirrors \/usr\/include\/dwarf.h.
module GHC.CmmToAsm.Dwarf.Constants where
......
......@@ -97,7 +97,7 @@ data NcgImpl statics instr jumpDest = NcgImpl {
-- and Note [Unwinding information in the NCG] in this module.
invertCondBranches :: Maybe CFG -> LabelMap RawCmmStatics -> [NatBasicBlock instr]
-> [NatBasicBlock instr]
-- ^ Turn the sequence of `jcc l1; jmp l2` into `jncc l2; <block_l1>`
-- ^ Turn the sequence of @jcc l1; jmp l2@ into @jncc l2; \<block_l1>@
-- when possible.
}
......
......@@ -5,6 +5,7 @@
-- Handling of join points
-- ~~~~~~~~~~~~~~~~~~~~~~~
--
-- @
-- B1: B2:
-- ... ...
-- RELOAD SLOT(0), %r1 RELOAD SLOT(0), %r1
......@@ -14,9 +15,11 @@
-- B3: ... C ...
-- RELOAD SLOT(0), %r1
-- ...
-- @
--
-- The Plan
-- ~~~~~~~~
--
-- As long as %r1 hasn't been written to in A, B or C then we don't need
-- the reload in B3.
--
......
......@@ -45,7 +45,7 @@ data CondCode
= CondCode Bool Cond InstrBlock
-- | a.k.a "Register64"
-- | a.k.a \"Register64\"
-- Reg is the lower 32-bit temporary which contains the result.
-- Use getHiVRegFromLo to find the other VRegUnique.
--
......
......@@ -252,8 +252,8 @@ dsLExpr (L loc e)
-- | Variant of 'dsLExpr' that ensures that the result is not levity
-- polymorphic. This should be used when the resulting expression will
-- be an argument to some other function.
-- See Note [Levity polymorphism checking] in GHC.HsToCore.Monad
-- See Note [Levity polymorphism invariants] in GHC.Core
-- See Note [Levity polymorphism checking] in "GHC.HsToCore.Monad"
-- See Note [Levity polymorphism invariants] in "GHC.Core"
dsLExprNoLP :: LHsExpr GhcTc -> DsM CoreExpr
dsLExprNoLP (L loc e)
= putSrcSpanDs loc $
......
......@@ -112,7 +112,7 @@ data EquationInfo
-- ^ The patterns for an equation
--
-- NB: We have /already/ applied 'decideBangHood' to
-- these patterns. See Note [decideBangHood] in GHC.HsToCore.Utils
-- these patterns. See Note [decideBangHood] in "GHC.HsToCore.Utils"
, eqn_orig :: Origin
-- ^ Was this equation present in the user source?
......
......@@ -982,7 +982,7 @@ storing required arguments along with the PmAltConLike in 'vi_neg'.
-- | Guess the universal argument types of a ConLike from an instantiation of
-- its result type. Rather easy for DataCons, but not so much for PatSynCons.
-- See Note [Pattern synonym result type] in GHC.Core.PatSyn.
-- See Note [Pattern synonym result type] in "GHC.Core.PatSyn".
guessConLikeUnivTyArgsFromResTy :: FamInstEnvs -> Type -> ConLike -> Maybe [Type]
guessConLikeUnivTyArgsFromResTy env res_ty (RealDataCon _) = do
(tc, tc_args) <- splitTyConApp_maybe res_ty
......
......@@ -31,7 +31,7 @@ import GHC.HsToCore.PmCheck.Oracle
-- | Pretty-print the guts of an uncovered value vector abstraction, i.e., its
-- components and refutable shapes associated to any mentioned variables.
--
-- Example for @([Just p, q], [p :-> [3,4], q :-> [0,5]]):
-- Example for @([Just p, q], [p :-> [3,4], q :-> [0,5]])@:
--
-- @
-- (Just p) q
......
......@@ -672,7 +672,7 @@ mkSelectorBinds :: [[Tickish Id]] -- ^ ticks to add, possibly
-> CoreExpr -- ^ Expression to which the pattern is bound
-> DsM (Id,[(Id,CoreExpr)])
-- ^ Id the rhs is bound to, for desugaring strict
-- binds (see Note [Desugar Strict binds] in GHC.HsToCore.Binds)
-- binds (see Note [Desugar Strict binds] in "GHC.HsToCore.Binds")
-- and all the desugared binds
mkSelectorBinds ticks pat val_expr
......
......@@ -59,7 +59,7 @@ data HieDictionary = HieDictionary
initBinMemSize :: Int
initBinMemSize = 1024*1024
-- | The header for HIE files - Capital ASCII letters "HIE".
-- | The header for HIE files - Capital ASCII letters \"HIE\".
hieMagic :: [Word8]
hieMagic = [72,73,69]
......
......@@ -660,12 +660,12 @@ computeInterface doc_str hi_boot_file mod0 = do
-- | Compute the signatures which must be compiled in order to
-- load the interface for a 'Module'. The output of this function
-- is always a subset of 'moduleFreeHoles'; it is more precise
-- because in signature @p[A=<A>,B=<B>]:B@, although the free holes
-- because in signature @p[A=\<A>,B=\<B>]:B@, although the free holes
-- are A and B, B might not depend on A at all!
--
-- If this is invoked on a signature, this does NOT include the
-- signature itself; e.g. precise free module holes of
-- @p[A=<A>,B=<B>]:B@ never includes B.
-- @p[A=\<A>,B=\<B>]:B@ never includes B.
moduleFreeHolesPrecise
:: SDoc -> Module
-> TcRnIf gbl lcl (MaybeErr MsgDoc (UniqDSet ModuleName))
......
{-# LANGUAGE CPP #-}
-- | Computing fingerprints of values serializeable with GHC's "Binary" module.
-- | Computing fingerprints of values serializeable with GHC's \"Binary\" module.
module GHC.Iface.Recomp.Binary
( -- * Computing fingerprints
fingerprintBinMem
......
......@@ -76,18 +76,18 @@ failWithRn doc = do
failM
-- | What we have is a generalized ModIface, which corresponds to
-- a module that looks like p[A=<A>]:B. We need a *specific* ModIface, e.g.
-- a module that looks like p[A=\<A>]:B. We need a *specific* ModIface, e.g.
-- p[A=q():A]:B (or maybe even p[A=\<B>]:B) which we load
-- up (either to merge it, or to just use during typechecking).
--
-- Suppose we have:
--
--
-- p[A=\<A>]:M ==> p[A=q():A]:M
--
--
-- Substitute all occurrences of \<A> with q():A (renameHoleModule).
-- Then, for any Name of form {A.T}, replace the Name with
-- the Name according to the exports of the implementing module.
-- the Name according to the exports of the implementing module.
-- This works even for p[A=\<B>]:M, since we just read in the
-- exports of B.hi, which is assumed to be ready now.
--
-- This function takes an optional 'NameShape', which can be used
......@@ -261,9 +261,9 @@ rnFieldLabel (FieldLabel l b sel) = do
-- | The key function. This gets called on every Name embedded
-- inside a ModIface. Our job is to take a Name from some
-- generalized unit ID p[A=<A>, B=<B>], and change
-- generalized unit ID p[A=\<A>, B=\<B>], and change
-- it to the correct name for a (partially) instantiated unit
-- ID, e.g. p[A=q[]:A, B=<B>].
-- ID, e.g. p[A=q[]:A, B=\<B>].
--
-- There are two important things to do:
--
......@@ -278,12 +278,12 @@ rnFieldLabel (FieldLabel l b sel) = do
-- interface precisely to "merge it in".
--
-- External case:
-- p[A=<B>]:A (and thisUnitId is something else)
-- p[A=\<B>]:A (and thisUnitId is something else)
-- We are loading this in order to determine B.hi! So
-- don't load B.hi to find the exports.
--
-- Local case:
-- p[A=<A>]:A (and thisUnitId is p[A=<A>])
-- p[A=\<A>]:A (and thisUnitId is p[A=\<A>])
-- This should not happen, because the rename is not necessary
-- in this case, but if it does we shouldn't load A.hi!
--
......
......@@ -199,7 +199,7 @@ data IfaceFamTyConFlav
| IfaceClosedSynFamilyTyCon (Maybe (IfExtName, [IfaceAxBranch]))
-- ^ Name of associated axiom and branches for pretty printing purposes,
-- or 'Nothing' for an empty closed family without an axiom
-- See Note [Pretty printing via Iface syntax] in GHC.Core.Ppr.TyThing
-- See Note [Pretty printing via Iface syntax] in "GHC.Core.Ppr.TyThing"
| IfaceAbstractClosedSynFamilyTyCon
| IfaceBuiltInSynFamTyCon -- for pretty printing purposes only
......@@ -720,7 +720,7 @@ data ShowHowMuch
| ShowSome [OccName] AltPpr
-- ^ Show only some sub-components. Specifically,
--
-- [@[]@] Print all sub-components.
-- [@\[\]@] Print all sub-components.
-- [@(n:ns)@] Print sub-component @n@ with @ShowSub = ns@;
-- elide other sub-components to @...@
-- May 14: the list is max 1 element long at the moment
......
......@@ -3,7 +3,7 @@
-- (c) 2014 I/O Tweag
--
-- Each module that uses 'static' keyword declares an initialization function of
-- the form hs_spt_init_<module>() which is emitted into the _stub.c file and
-- the form hs_spt_init_\<module>() which is emitted into the _stub.c file and
-- annotated with __attribute__((constructor)) so that it gets executed at
-- startup time.
--
......@@ -28,7 +28,7 @@
--
-- The linker must find the definitions matching the @extern StgPtr <name>@
-- declarations. For this to work, the identifiers of static pointers need to be
-- exported. This is done in GHC.Core.Opt.SetLevels.newLvlVar.
-- exported. This is done in 'GHC.Core.Opt.SetLevels.newLvlVar'.
--
-- There is also a finalization function for the time when the module is
-- unloaded.
......
......@@ -154,7 +154,7 @@ type IfaceKind = IfaceType
-- | A kind of universal type, used for types and kinds.
--
-- Any time a 'Type' is pretty-printed, it is first converted to an 'IfaceType'
-- before being printed. See Note [Pretty printing via Iface syntax] in GHC.Core.Ppr.TyThing
-- before being printed. See Note [Pretty printing via Iface syntax] in "GHC.Core.Ppr.TyThing"
data IfaceType
= IfaceFreeTyVar TyVar -- See Note [Free tyvars in IfaceType]
| IfaceTyVar IfLclName -- Type/coercion variable only, not tycon
......
......@@ -6,7 +6,7 @@
-- LLVM binding library in Haskell, but enough to generate code for GHC.
--
-- This code is derived from code taken from the Essential Haskell Compiler
-- (EHC) project (<http://www.cs.uu.nl/wiki/Ehc/WebHome>).
-- (EHC) project.
--
module GHC.Llvm (
......
......@@ -12,8 +12,8 @@ import GHC.Utils.Outputable
--
-- The LLVM metadata feature is poorly documented but roughly follows the
-- following design:
-- * Metadata can be constructed in a few different ways (See below).
-- * After which it can either be attached to LLVM statements to pass along
-- - Metadata can be constructed in a few different ways (See below).
-- - After which it can either be attached to LLVM statements to pass along
-- extra information to the optimizer and code generator OR specifically named
-- metadata has an affect on the whole module (i.e., linking behaviour).
--
......@@ -21,18 +21,18 @@ import GHC.Utils.Outputable
-- # Constructing metadata
-- Metadata comes largely in three forms:
--
-- * Metadata expressions -- these are the raw metadata values that encode
-- - Metadata expressions -- these are the raw metadata values that encode
-- information. They consist of metadata strings, metadata nodes, regular
-- LLVM values (both literals and references to global variables) and
-- metadata expressions (i.e., recursive data type). Some examples:
-- !{ !"hello", !0, i32 0 }
-- !{ !1, !{ i32 0 } }
--
-- * Metadata nodes -- global metadata variables that attach a metadata
-- - Metadata nodes -- global metadata variables that attach a metadata
-- expression to a number. For example:
-- !0 = !{ [<metadata expressions>] !}
--
-- * Named metadata -- global metadata variables that attach a metadata nodes
-- - Named metadata -- global metadata variables that attach a metadata nodes
-- to a name. Used ONLY to communicated module level information to LLVM
-- through a meaningful name. For example:
-- !llvm.module.linkage = !{ !0, !1 }
......@@ -41,7 +41,7 @@ import GHC.Utils.Outputable
-- # Using Metadata
-- Using metadata depends on the form it is in:
--
-- * Attach to instructions -- metadata can be attached to LLVM instructions
-- - Attach to instructions -- metadata can be attached to LLVM instructions
-- using a specific reference as follows:
-- %l = load i32* @glob, !nontemporal !10
-- %m = load i32* @glob, !nontemporal !{ i32 0, !{ i32 0 } }
......@@ -49,12 +49,12 @@ import GHC.Utils.Outputable
-- Refer to LLVM documentation for which instructions take metadata and its
-- meaning.
--
-- * As arguments -- llvm functions can take metadata as arguments, for
-- - As arguments -- llvm functions can take metadata as arguments, for
-- example:
-- call void @llvm.dbg.value(metadata !{ i32 0 }, i64 0, metadata !1)
-- As with instructions, only metadata nodes or expressions can be attached.
--
-- * As a named metadata -- Here the metadata is simply declared in global
-- - As a named metadata -- Here the metadata is simply declared in global
-- scope using a specific name to communicate module level information to LLVM.
-- For example:
-- !llvm.module.linkage = !{ !0, !1 }
......@@ -82,8 +82,8 @@ data MetaAnnot = MetaAnnot LMString MetaExpr
-- | Metadata declarations. Metadata can only be declared in global scope.
data MetaDecl
-- | Named metadata. Only used for communicating module information to
-- LLVM. ('!name = !{ [!<n>] }' form).
-- LLVM. ('!name = !{ [!\<n>] }' form).
= MetaNamed !LMString [MetaId]
-- | Metadata node declaration.
-- ('!0 = metadata !{ <metadata expression> }' form).
-- ('!0 = metadata !{ \<metadata expression> }' form).
| MetaUnnamed !MetaId !MetaExpr
......@@ -93,7 +93,7 @@ type HowInScope = Either SrcSpan ImpDeclSpec
-- Right ispec => imported as specified by ispec
-- | Called from the typechecker (GHC.Tc.Errors) when we find an unbound variable
-- | Called from the typechecker ("GHC.Tc.Errors") when we find an unbound variable
unknownNameSuggestions :: DynFlags
-> HomePackageTable -> Module
-> GlobalRdrEnv -> LocalRdrEnv -> ImportAvails
......
......@@ -148,7 +148,7 @@ halfWordSizeInBits platform = platformWordSizeInBits platform `div` 2
-}
-- | A description of the layout of a closure. Corresponds directly
-- to the closure types in includes/rts/storage/ClosureTypes.h.
-- to the closure types in includes\/rts\/storage\/ClosureTypes.h.
data SMRep
= HeapRep -- GC routines consult sizes in info tbl
IsStatic
......@@ -173,7 +173,7 @@ data SMRep
Int -- type tags, so this form lets us override the default
SMRep -- tag for an SMRep.
-- | True <=> This is a static closure. Affects how we garbage-collect it.
-- | True \<=> This is a static closure. Affects how we garbage-collect it.
-- Static closure have an extra static link field at the end.
-- Constructors do not have a static variant; see Note [static constructors]
type IsStatic = Bool
......@@ -274,12 +274,12 @@ isStaticNoCafCon _ = False
fixedHdrSize :: DynFlags -> ByteOff
fixedHdrSize dflags = wordsToBytes (targetPlatform dflags) (fixedHdrSizeW dflags)
-- | Size of a closure header (StgHeader in includes/rts/storage/Closures.h)
-- | Size of a closure header (StgHeader in includes\/rts\/storage\/Closures.h)
fixedHdrSizeW :: DynFlags -> WordOff
fixedHdrSizeW dflags = sTD_HDR_SIZE dflags + profHdrSize dflags
-- | Size of the profiling part of a closure header
-- (StgProfHeader in includes/rts/storage/Closures.h)
-- (StgProfHeader in includes\/rts\/storage\/Closures.h)
profHdrSize :: DynFlags -> WordOff
profHdrSize dflags
| gopt Opt_SccProfilingOn dflags = pROF_HDR_SIZE dflags
......
......@@ -91,7 +91,7 @@ data Unlinked
-- carries some static pointer table entries which
-- should be loaded along with the BCOs.
-- See Note [Grant plan for static forms] in
-- GHC.Iface.Tidy.StaticPtrTable.
-- "GHC.Iface.Tidy.StaticPtrTable".
instance Outputable Unlinked where
ppr (DotO path) = text "DotO" <+> text path
......@@ -100,7 +100,7 @@ instance Outputable Unlinked where
ppr (BCOs bcos spt) = text "BCOs" <+> ppr bcos <+> ppr spt
-- | An entry to be inserted into a module's static pointer table.
-- See Note [Grand plan for static forms] in GHC.Iface.Tidy.StaticPtrTable.
-- See Note [Grand plan for static forms] in "GHC.Iface.Tidy.StaticPtrTable".
data SptEntry = SptEntry Id Fingerprint
instance Outputable SptEntry where
......
......@@ -144,7 +144,7 @@ nonVoidIds ids = [NonVoid id | id <- ids, not (isVoidTy (idType id))]
-- | Used in places where some invariant ensures that all these Ids are
-- non-void; e.g. constructor field binders in case expressions.
-- See Note [Post-unarisation invariants] in GHC.Stg.Unarise.
-- See Note [Post-unarisation invariants] in "GHC.Stg.Unarise".
assertNonVoidIds :: [Id] -> [NonVoid Id]
assertNonVoidIds ids = ASSERT(not (any (isVoidTy . idType) ids))
coerce ids
......@@ -154,7 +154,7 @@ nonVoidStgArgs args = [NonVoid arg | arg <- args, not (isVoidTy (stgArgType arg)
-- | Used in places where some invariant ensures that all these arguments are
-- non-void; e.g. constructor arguments.
-- See Note [Post-unarisation invariants] in GHC.Stg.Unarise.
-- See Note [Post-unarisation invariants] in "GHC.Stg.Unarise".
assertNonVoidStgArgs :: [StgArg] -> [NonVoid StgArg]
assertNonVoidStgArgs args = ASSERT(not (any (isVoidTy . stgArgType) args))
coerce args
......
......@@ -344,7 +344,7 @@ entryHeapCheck cl_info nodeSet arity args code
Just (_, ArgGen _) -> False
_otherwise -> True
-- | lower-level version for GHC.Cmm.Parser
-- | lower-level version for "GHC.Cmm.Parser"
entryHeapCheck' :: Bool -- is a known function pattern
-> CmmExpr -- expression for the closure pointer
-> Int -- Arity -- not same as len args b/c of voids
......
......@@ -348,8 +348,8 @@ parseError s0 = case breakColon s0 of
-- taking care to ignore colons in Windows drive letters (as noted in #17786).
-- For instance,
--
-- * @"hi.c: ABCD"@ is mapped to @Just ("hi.c", "ABCD")@
-- * @"C:\hi.c: ABCD"@ is mapped to @Just ("C:\hi.c", "ABCD")@
-- * @"hi.c: ABCD"@ is mapped to @Just ("hi.c", \"ABCD\")@
-- * @"C:\\hi.c: ABCD"@ is mapped to @Just ("C:\\hi.c", \"ABCD\")@
breakColon :: String -> Maybe (String, String)
breakColon = go []
where
......
......@@ -13,7 +13,7 @@
-- | Generating derived instance declarations
--
-- This module is nominally ``subordinate'' to @GHC.Tc.Deriv@, which is the
-- This module is nominally ``subordinate'' to "GHC.Tc.Deriv", which is the
-- ``official'' interface to deriving-related things.
--
-- This is where we do all the grimy bindings' generation.
......
......@@ -60,7 +60,7 @@ import qualified GHC.LanguageExtensions as LangExt
import GHC.Data.List.SetOps (assocMaybe)
-- | To avoid having to manually plumb everything in 'DerivEnv' throughout
-- various functions in @GHC.Tc.Deriv@ and @GHC.Tc.Deriv.Infer@, we use 'DerivM', which
-- various functions in "GHC.Tc.Deriv" and "GHC.Tc.Deriv.Infer", we use 'DerivM', which
-- is a simple reader around 'TcRn'.
type DerivM = ReaderT DerivEnv TcRn
......
......@@ -166,7 +166,7 @@ reportUnsolved wanted
-- NB: Type-level holes are OK, because there are no bindings.
-- See Note [Deferring coercion errors to runtime]
-- Used by solveEqualities for kind equalities
-- (see Note [Fail fast on kind errors] in GHC.Tc.Solver)
-- (see Note [Fail fast on kind errors] in "GHC.Tc.Solver")
-- and for simplifyDefault.
reportAllUnsolved :: WantedConstraints -> TcM ()
reportAllUnsolved wanted
......@@ -183,7 +183,7 @@ reportAllUnsolved wanted
-- | Report all unsolved goals as warnings (but without deferring any errors to
-- run-time). See Note [Safe Haskell Overlapping Instances Implementation] in
-- GHC.Tc.Solver
-- "GHC.Tc.Solver"
warnAllUnsolved :: WantedConstraints -> TcM ()
warnAllUnsolved wanted
= do { ev_binds <- newTcEvBinds
......
......@@ -7,7 +7,7 @@
{-# LANGUAGE CPP #-}
{-# LANGUAGE TypeFamilies #-}
-- | Typechecking \tr{foreign} declarations
-- | Typechecking @foreign@ declarations
--
-- A foreign declaration is used to either give an externally
-- implemented function a Haskell type (and calling interface) or
......
......@@ -3036,7 +3036,7 @@ zonkAndScopedSort spec_tkvs
-- you likely need to push the level before creating whatever type
-- gets passed here. Any variable whose level is greater than the
-- ambient level but is not selected to be generalized will be
-- promoted. (See [Promoting unification variables] in GHC.Tc.Solver
-- promoted. (See [Promoting unification variables] in "GHC.Tc.Solver"
-- and Note [Recipe for checking a signature].)
-- The resulting KindVar are the variables to
-- quantify over, in the correct, well-scoped order. They should
......@@ -3240,7 +3240,7 @@ data DataSort
--
-- 2. @k@ (where @k@ is a bare kind variable; see #12369)
--
-- See also Note [Datatype return kinds] in GHC.Tc.TyCl
-- See also Note [Datatype return kinds] in "GHC.Tc.TyCl"
checkDataKindSig :: DataSort -> Kind -> TcM ()
checkDataKindSig data_sort kind = do
dflags <- getDynFlags
......
......@@ -60,7 +60,7 @@ data AssocInstInfo
| InClsInst { ai_class :: Class
, ai_tyvars :: [TyVar] -- ^ The /scoped/ tyvars of the instance
-- Why scoped? See bind_me in
-- GHC.Tc.Validity.checkConsistentFamInst
-- 'GHC.Tc.Validity.checkConsistentFamInst'
, ai_inst_env :: VarEnv Type -- ^ Maps /class/ tyvars to their instance types
-- See Note [Matching in the consistent-instantiation check]
}
......
......@@ -736,7 +736,7 @@ checkForInjectivityConflicts instEnvs famInst
-- this is possible and False if adding this equation would violate injectivity
-- annotation. This looks only at the one equation; it does not look for
-- interaction between equations. Use checkForInjectivityConflicts for that.
-- Does checks (2)-(4) of Note [Verifying injectivity annotation] in GHC.Core.FamInstEnv.
-- Does checks (2)-(4) of Note [Verifying injectivity annotation] in "GHC.Core.FamInstEnv".
checkInjectiveEquation :: FamInst -> TcM ()
checkInjectiveEquation famInst
| isTypeFamilyTyCon tycon
......
......@@ -147,7 +147,7 @@ There are many wrinkles:
-- entry-point of this module and is invoked by the typechecker driver in
-- 'tcRnSrcDecls'.
--
-- See Note [Grand plan for Typeable] in GHC.Tc.Instance.Typeable.
-- See Note [Grand plan for Typeable] in "GHC.Tc.Instance.Typeable".
mkTypeableBinds :: TcM TcGblEnv
mkTypeableBinds
= do { dflags <- getDynFlags
......@@ -346,7 +346,7 @@ mkPrimTypeableTodos
-- The majority of the types we need here are contained in 'primTyCons'.
-- However, not all of them: in particular unboxed tuples are absent since we
-- don't want to include them in the original name cache. See
-- Note [Built-in syntax and the OrigNameCache] in GHC.Iface.Env for more.
-- Note [Built-in syntax and the OrigNameCache] in "GHC.Iface.Env" for more.
ghcPrimTypeableTyCons :: [TyCon]
ghcPrimTypeableTyCons = concat
[ [ runtimeRepTyCon, vecCountTyCon, vecElemTyCon, funTyCon ]
......
......@@ -831,11 +831,11 @@ the let binding.
-- | How should we choose which constraints to quantify over?
data InferMode = ApplyMR -- ^ Apply the monomorphism restriction,
-- never quantifying over any constraints
| EagerDefaulting -- ^ See Note [TcRnExprMode] in GHC.Tc.Module,
| EagerDefaulting -- ^ See Note [TcRnExprMode] in "GHC.Tc.Module",
-- the :type +d case; this mode refuses
-- to quantify over any defaultable constraint
| NoRestrictions -- ^ Quantify over any constraint that
-- satisfies TcType.pickQuantifiablePreds
-- satisfies 'GHC.Tc.Utils.TcType.pickQuantifiablePreds'
instance Outputable InferMode where
ppr ApplyMR = text "ApplyMR"
......
......@@ -767,7 +767,7 @@ when trying to find derived equalities arising from injectivity.
-- If (xi, co) <- flatten mode ev ty, then co :: xi ~r ty
-- where r is the role in @ev@. If @mode@ is 'FM_FlattenAll',
-- then 'xi' is almost function-free (Note [Almost function-free]
-- in GHC.Tc.Types).
-- in "GHC.Tc.Types").
flatten :: FlattenMode -> CtEvidence -> TcType
-> TcS (Xi, TcCoercion)
flatten mode ev ty
......
......@@ -2488,7 +2488,7 @@ matchClassInst dflags inerts clas tys loc
-- | If a class is "naturally coherent", then we needn't worry at all, in any
-- way, about overlapping/incoherent instances. Just solve the thing!
-- See Note [Naturally coherent classes]
-- See also Note [The equality class story] in GHC.Builtin.Types.Prim.
-- See also Note [The equality class story] in "GHC.Builtin.Types.Prim".
naturallyCoherentClass :: Class -> Bool
naturallyCoherentClass cls
= isCTupleClass cls
......
......@@ -728,7 +728,7 @@ data InertCans -- See Note [Detailed InertCans Invariants] for more
-- failure.
--
-- ^ See Note [Safe Haskell Overlapping Instances Implementation]
-- in GHC.Tc.Solver
-- in "GHC.Tc.Solver"
, inert_irreds :: Cts
-- Irreducible predicates that cannot be made canonical,
......@@ -2177,7 +2177,7 @@ getNoGivenEqs tclvl skol_tvs
-- | Returns Given constraints that might,
-- potentially, match the given pred. This is used when checking to see if a
-- Given might overlap with an instance. See Note [Instance and Given overlap]
-- in GHC.Tc.Solver.Interact.
-- in "GHC.Tc.Solver.Interact"
matchableGivens :: CtLoc -> PredType -> InertSet -> Cts
matchableGivens loc_w pred_w (IS { inert_cans = inert_cans })
= filterBag matchable_given all_relevant_givens
......
......@@ -4781,7 +4781,7 @@ wrongKindOfFamily family
-- | Produce an error for oversaturated type family equations with too many
-- required arguments.
-- See Note [Oversaturated type family equations] in GHC.Tc.Validity.
-- See Note [Oversaturated type family equations] in "GHC.Tc.Validity".
wrongNumberOfParmsErr :: Arity -> SDoc
wrongNumberOfParmsErr max_args
= text "Number of parameters must match family declaration; expected"
......
......@@ -9,7 +9,7 @@
-- | Various types used during typechecking.
--
-- Please see GHC.Tc.Utils.Monad as well for operations on these types. You probably
-- Please see "GHC.Tc.Utils.Monad" as well for operations on these types. You probably
-- want to import it, instead of this module.
--
-- All the monads exported here are built on top of the same IOEnv monad. The
......@@ -144,14 +144,14 @@ import qualified Language.Haskell.TH as TH
-- | A 'NameShape' is a substitution on 'Name's that can be used
-- to refine the identities of a hole while we are renaming interfaces
-- (see 'GHC.Iface.Rename'). Specifically, a 'NameShape' for
-- (see "GHC.Iface.Rename"). Specifically, a 'NameShape' for
-- 'ns_module_name' @A@, defines a mapping from @{A.T}@
-- (for some 'OccName' @T@) to some arbitrary other 'Name'.
--
-- The most intruiging thing about a 'NameShape', however, is
-- how it's constructed. A 'NameShape' is *implied* by the
-- exported 'AvailInfo's of the implementor of an interface:
-- if an implementor of signature @<H>@ exports @M.T@, you implicitly
-- if an implementor of signature @\<H>@ exports @M.T@, you implicitly
-- define a substitution from @{H.T}@ to @M.T@. So a 'NameShape'
-- is computed from the list of 'AvailInfo's that are exported
-- by the implementation of a module, or successively merged
......@@ -419,7 +419,7 @@ data TcGblEnv
tcg_fix_env :: FixityEnv, -- ^ Just for things in this module
tcg_field_env :: RecFieldEnv, -- ^ Just for things in this module
-- See Note [The interactive package] in GHC.Driver.Types
-- See Note [The interactive package] in "GHC.Driver.Types"
tcg_type_env :: TypeEnv,
-- ^ Global type env for the module we are compiling now. All
......@@ -430,7 +430,7 @@ data TcGblEnv
-- move to the global envt during zonking)
--
-- NB: for what "things in this module" means, see
-- Note [The interactive package] in GHC.Driver.Types
-- Note [The interactive package] in "GHC.Driver.Types"
tcg_type_env_var :: TcRef TypeEnv,
-- Used only to initialise the interface-file
......@@ -477,7 +477,7 @@ data TcGblEnv
-- (tcRnExports)
-- - imp_mods is used to compute usage info (mkIfaceTc, deSugar)
-- - imp_trust_own_pkg is used for Safe Haskell in interfaces
-- (mkIfaceTc, as well as in GHC.Driver.Main)
-- (mkIfaceTc, as well as in "GHC.Driver.Main")
-- - To create the Dependencies field in interface (mkDependencies)
-- These three fields track unused bindings and imports
......@@ -487,7 +487,7 @@ data TcGblEnv
tcg_keep :: TcRef NameSet,
tcg_th_used :: TcRef Bool,
-- ^ @True@ <=> Template Haskell syntax used.
-- ^ @True@ \<=> Template Haskell syntax used.
--
-- We need this so that we can generate a dependency on the
-- Template Haskell package, because the desugarer is going
......@@ -496,7 +496,7 @@ data TcGblEnv
-- mutable variable.
tcg_th_splice_used :: TcRef Bool,
-- ^ @True@ <=> A Template Haskell splice was used.
-- ^ @True@ \<=> A Template Haskell splice was used.
--
-- Splices disable recompilation avoidance (see #481)
......@@ -523,7 +523,7 @@ data TcGblEnv
-- voluminous and are needed if you want to report unused imports
tcg_rn_decls :: Maybe (HsGroup GhcRn),
-- ^ Renamed decls, maybe. @Nothing@ <=> Don't retain renamed
-- ^ Renamed decls, maybe. @Nothing@ \<=> Don't retain renamed
-- decls.
tcg_dependent_files :: TcRef [FilePath], -- ^ dependencies from addDependentFile
......@@ -1059,7 +1059,7 @@ data ArrowCtxt -- Note [Escaping the arrow scope]
-- | A typecheckable thing available in a local context. Could be
-- 'AGlobal' 'TyThing', but also lexically scoped variables, etc.
-- See 'GHC.Tc.Utils.Env' for how to retrieve a 'TyThing' given a 'Name'.
-- See "GHC.Tc.Utils.Env" for how to retrieve a 'TyThing' given a 'Name'.
data TcTyThing
= AGlobal TyThing -- Used only in the return type of a lookup
......@@ -1112,9 +1112,9 @@ instance Outputable TcTyThing where -- Debugging only
-- | IdBindingInfo describes how an Id is bound.
--
-- It is used for the following purposes:
-- a) for static forms in 'GHC.Tc.Gen.Expr.checkClosedInStaticForm' and
-- b) to figure out when a nested binding can be generalised,
-- b) to figure out when a nested binding can be generalised,
-- in 'GHC.Tc.Gen.Bind.decideGeneralisationPlan'.
--
data IdBindingInfo -- See Note [Meaning of IdBindingInfo and ClosedTypeId]
= NotLetBound
......@@ -1336,7 +1336,7 @@ data ImportAvails
-- = ModuleEnv [ImportedModsVal],
-- ^ Domain is all directly-imported modules
--
-- See the documentation on ImportedModsVal in GHC.Driver.Types for the
-- See the documentation on ImportedModsVal in "GHC.Driver.Types" for the
-- meaning of the fields.
--
-- We need a full ModuleEnv rather than a ModuleNameEnv here,
......@@ -1368,13 +1368,13 @@ data ImportAvails
-- where True for the bool indicates the package is required to be
-- trusted is the more logical design, doing so complicates a lot
-- of code not concerned with Safe Haskell.
-- See Note [Tracking Trust Transitively] in GHC.Rename.Names
-- See Note [Tracking Trust Transitively] in "GHC.Rename.Names"
imp_trust_own_pkg :: Bool,
-- ^ Do we require that our own package is trusted?
-- This is to handle efficiently the case where a Safe module imports
-- a Trustworthy module that resides in the same package as it.
-- See Note [Trust Own Package] in GHC.Rename.Names
-- See Note [Trust Own Package] in "GHC.Rename.Names"
imp_orphs :: [Module],
-- ^ Orphan modules below us in the import tree (and maybe including
......
......@@ -484,12 +484,12 @@ tyCoVarsOfCt :: Ct -> TcTyCoVarSet
tyCoVarsOfCt = fvVarSet . tyCoFVsOfCt
-- | Returns free variables of constraints as a deterministically ordered.
-- list. See Note [Deterministic FV] in GHC.Utils.FV.
-- list. See Note [Deterministic FV] in "GHC.Utils.FV".
tyCoVarsOfCtList :: Ct -> [TcTyCoVar]
tyCoVarsOfCtList = fvVarList . tyCoFVsOfCt