Fix several note references

24 files changed, 40 insertions, 44 deletions

diff --git a/compiler/GHC/Core/Opt/Simplify.hs b/compiler/GHC/Core/Opt/Simplify.hs
index c5fd3dfef1..0ea3c1f3f6 100644
--- a/compiler/GHC/Core/Opt/Simplify.hs
+++ b/compiler/GHC/Core/Opt/Simplify.hs
@@ -4169,7 +4169,7 @@ Wrinkles
   GHC.Core.Opt.Simplify.Utils
 
 * Don't eta-expand a trivial expr, else each pass will eta-reduce it,
-  and then eta-expand again. See Note [Do not eta-expand trivial expressions]
+  and then eta-expand again. See Note [Which RHSs do we eta-expand?]
   in GHC.Core.Opt.Simplify.Utils.
 
 * Don't eta-expand join points; see Note [Do not eta-expand join points]
diff --git a/compiler/GHC/Core/Opt/Specialise.hs b/compiler/GHC/Core/Opt/Specialise.hs
index b59adbd511..63eb05da06 100644
--- a/compiler/GHC/Core/Opt/Specialise.hs
+++ b/compiler/GHC/Core/Opt/Specialise.hs
@@ -1644,7 +1644,7 @@ we simply extend the CallKey with trailing UnspecArgs, so we'll
 generate a rule that completely saturates the DFun.
 
 There is an ASSERT that checks this, in the DFunUnfolding case of
-GHC.Core.Unfold.specUnfolding.
+GHC.Core.Unfold.Make.specUnfolding.
 
 Note [Specialisation Must Preserve Sharing]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/compiler/GHC/Core/Subst.hs b/compiler/GHC/Core/Subst.hs
index e6f0237f32..be658384b0 100644
--- a/compiler/GHC/Core/Subst.hs
+++ b/compiler/GHC/Core/Subst.hs
@@ -97,8 +97,8 @@ data Subst
         -- This is what lets us deal with name capture properly
         -- It's a hard invariant to check...
         --
-        -- INVARIANT 2: The substitution is apply-once; see Note [Apply once] with
-        --              Types.TvSubstEnv
+        -- INVARIANT 2: The substitution is apply-once;
+        --              see Note [Substitutions apply only once] in GHC.Core.TyCo.Subst
         --
         -- INVARIANT 3: See Note [Extending the Subst]
 
@@ -108,7 +108,7 @@ Note [Extending the Subst]
 For a core Subst, which binds Ids as well, we make a different choice for Ids
 than we do for TyVars.
 
-For TyVars, see Note [Extending the TCvSubst] in GHC.Core.TyCo.Subst.
+For TyVars, see Note [Extending the TCvSubstEnv] in GHC.Core.TyCo.Subst.
 
 For Ids, we have a different invariant
         The IdSubstEnv is extended *only* when the Unique on an Id changes
diff --git a/compiler/GHC/Core/TyCo/FVs.hs b/compiler/GHC/Core/TyCo/FVs.hs
index e837132fc0..b40d930b3c 100644
--- a/compiler/GHC/Core/TyCo/FVs.hs
+++ b/compiler/GHC/Core/TyCo/FVs.hs
@@ -283,7 +283,7 @@ tyCoVarsOfTypes tys = runTyCoVars (deep_tys tys)
 --   tyCoVarsOfTypes tys = closeOverKinds (shallowTyCoVarsOfTypes tys)
 
 tyCoVarsOfCo :: Coercion -> TyCoVarSet
--- See Note [Free variables of Coercions]
+-- See Note [Free variables of types]
 tyCoVarsOfCo co = runTyCoVars (deep_co co)
 
 tyCoVarsOfMCo :: MCoercion -> TyCoVarSet
diff --git a/compiler/GHC/Core/TyCo/Ppr.hs b/compiler/GHC/Core/TyCo/Ppr.hs
index 2929474d84..5f1a802dfe 100644
--- a/compiler/GHC/Core/TyCo/Ppr.hs
+++ b/compiler/GHC/Core/TyCo/Ppr.hs
@@ -68,17 +68,11 @@ parens around the type, except for the atomic cases.  @pprParendType@
 works just by setting the initial context precedence very high.
 
 Note that any function which pretty-prints a @Type@ first converts the @Type@
-to an @IfaceType@. See Note [IfaceType and pretty-printing] in GHC.Iface.Type.
+to an @IfaceType@. See Note [Pretty printing via Iface syntax] in GHC.Types.TyThing.Ppr.
 
 See Note [Precedence in types] in GHC.Types.Basic.
 -}
 
---------------------------------------------------------
--- When pretty-printing types, we convert to IfaceType,
---   and pretty-print that.
--- See Note [Pretty printing via Iface syntax] in GHC.Types.TyThing.Ppr
---------------------------------------------------------
-
 pprType, pprParendType, pprTidiedType :: Type -> SDoc
 pprType       = pprPrecType topPrec
 pprParendType = pprPrecType appPrec
diff --git a/compiler/GHC/Core/TyCo/Subst.hs b/compiler/GHC/Core/TyCo/Subst.hs
index a5cb32e38e..7322ff5e03 100644
--- a/compiler/GHC/Core/TyCo/Subst.hs
+++ b/compiler/GHC/Core/TyCo/Subst.hs
@@ -781,7 +781,7 @@ substTyCoVar subst tv
   | otherwise = CoercionTy $ substCoVar subst tv
 
 lookupTyVar :: TCvSubst -> TyVar  -> Maybe Type
-        -- See Note [Extending the TCvSubst]
+        -- See Note [Extending the TCvSubstEnv]
 lookupTyVar (TCvSubst _ tenv _) tv
   = assert (isTyVar tv )
     lookupVarEnv tenv tv
@@ -998,7 +998,7 @@ substTyVarBndrUsing subst_fn subst@(TCvSubst in_scope tenv cenv) old_var
     no_change = no_kind_change && (new_var == old_var)
         -- no_change means that the new_var is identical in
         -- all respects to the old_var (same unique, same kind)
-        -- See Note [Extending the TCvSubst]
+        -- See Note [Extending the TCvSubstEnv]
         --
         -- In that case we don't need to extend the substitution
         -- to map old to new.  But instead we must zap any
diff --git a/compiler/GHC/Core/TyCon.hs b/compiler/GHC/Core/TyCon.hs
index 48da8e8275..ab30175cb2 100644
--- a/compiler/GHC/Core/TyCon.hs
+++ b/compiler/GHC/Core/TyCon.hs
@@ -958,7 +958,7 @@ data TyCon
 
         -- See Note [The binders/kind/arity fields of a TyCon]
         tyConBinders :: [TyConTyCoBinder], -- ^ Full binders
-           -- TyConTyCoBinder: see Note [Promoted GADT data construtors]
+           -- TyConTyCoBinder: see Note [Promoted GADT data constructors]
         tyConResKind :: Kind,             -- ^ Result kind
         tyConKind    :: Kind,             -- ^ Kind of this TyCon
         tyConArity   :: Arity,            -- ^ Arity
@@ -2439,7 +2439,7 @@ setTcTyConKind :: TyCon -> Kind -> TyCon
 -- See Note [The Purely Kinded Type Invariant (PKTI)] in GHC.Tc.Gen.HsType
 setTcTyConKind tc@(TcTyCon {}) kind = let tc' = tc { tyConKind = kind
                                                    , tyConNullaryTy = mkNakedTyConTy tc'
-                                                       -- see Note [Sharing nullary TyCons]
+                                                       -- see Note [Sharing nullary TyConApps]
                                                    }
                                       in tc'
 setTcTyConKind tc              _    = pprPanic "setTcTyConKind" (ppr tc)
diff --git a/compiler/GHC/Core/Unfold.hs b/compiler/GHC/Core/Unfold.hs
index cd9944c0a0..0ff846d79e 100644
--- a/compiler/GHC/Core/Unfold.hs
+++ b/compiler/GHC/Core/Unfold.hs
@@ -1173,7 +1173,7 @@ tryUnfolding logger opts !case_depth id lone_variable
 
      UnfWhen { ug_arity = uf_arity, ug_unsat_ok = unsat_ok, ug_boring_ok = boring_ok }
         | enough_args && (boring_ok || some_benefit || unfoldingVeryAggressive opts)
-                -- See Note [INLINE for small functions (3)]
+                -- See Note [INLINE for small functions] (3)
         -> traceInline logger opts id str (mk_doc some_benefit empty True) (Just unf_template)
         | otherwise
         -> traceInline logger opts id str (mk_doc some_benefit empty False) Nothing
@@ -1244,7 +1244,7 @@ tryUnfolding logger opts !case_depth id lone_variable
           = case cont_info of
               CaseCtxt   -> not (lone_variable && is_exp)  -- Note [Lone variables]
               ValAppCtxt -> True                           -- Note [Cast then apply]
-              RuleArgCtxt -> uf_arity > 0  -- See Note [Unfold info lazy contexts]
+              RuleArgCtxt -> uf_arity > 0  -- See Note [Unfold into lazy contexts]
               DiscArgCtxt -> uf_arity > 0  -- Note [Inlining in ArgCtxt]
               RhsCtxt     -> uf_arity > 0  --
               _other      -> False         -- See Note [Nested functions]
diff --git a/compiler/GHC/Core/Unfold/Make.hs b/compiler/GHC/Core/Unfold/Make.hs
index 44aa6ba1db..134c8bce69 100644
--- a/compiler/GHC/Core/Unfold/Make.hs
+++ b/compiler/GHC/Core/Unfold/Make.hs
@@ -154,7 +154,7 @@ specUnfolding opts spec_bndrs spec_app rule_lhs_args
               df@(DFunUnfolding { df_bndrs = old_bndrs, df_con = con, df_args = args })
   = assertPpr (rule_lhs_args `equalLength` old_bndrs)
               (ppr df $$ ppr rule_lhs_args) $
-           -- For this ASSERT see Note [DFunUnfoldings] in GHC.Core.Opt.Specialise
+           -- For this ASSERT see Note [Specialising DFuns] in GHC.Core.Opt.Specialise
     mkDFunUnfolding spec_bndrs con (map spec_arg args)
       -- For DFunUnfoldings we transform
       --       \obs. MkD <op1> ... <opn>
diff --git a/compiler/GHC/Core/Utils.hs b/compiler/GHC/Core/Utils.hs
index b7b1c9334b..eea81d1502 100644
--- a/compiler/GHC/Core/Utils.hs
+++ b/compiler/GHC/Core/Utils.hs
@@ -946,7 +946,7 @@ combineIdenticalAlts imposs_deflt_cons (Alt con1 bndrs1 rhs1 : rest_alts)
     imposs_deflt_cons' = imposs_deflt_cons `minusList` elim_cons
     elim_cons = elim_con1 ++ map (\(Alt con _ _) -> con) elim_rest
     elim_con1 = case con1 of     -- Don't forget con1!
-                  DEFAULT -> []  -- See Note [
+                  DEFAULT -> []
                   _       -> [con1]
 
     cheapEqTicked e1 e2 = cheapEqExpr' tickishFloatable e1 e2
diff --git a/compiler/GHC/Driver/Session.hs b/compiler/GHC/Driver/Session.hs
index 997eb94140..b78d141061 100644
--- a/compiler/GHC/Driver/Session.hs
+++ b/compiler/GHC/Driver/Session.hs
@@ -1985,7 +1985,7 @@ safeFlagCheck cmdl dflags =
                     "-fpackage-trust ignored;" ++
                     " must be specified with a Safe Haskell flag"]
 
-    -- Have we inferred Unsafe? See Note [GHC.Driver.Main . Safe Haskell Inference]
+    -- Have we inferred Unsafe? See Note [Safe Haskell Inference] in GHC.Driver.Main
     safeFlags = all (\(_,_,t,_) -> not $ t dflags) unsafeFlagsForInfer
 
 
diff --git a/compiler/GHC/Iface/Syntax.hs b/compiler/GHC/Iface/Syntax.hs
index 9b89d7f145..bfd07fda8b 100644
--- a/compiler/GHC/Iface/Syntax.hs
+++ b/compiler/GHC/Iface/Syntax.hs
@@ -704,7 +704,8 @@ instance Outputable IfaceDecl where
   ppr = pprIfaceDecl showToIface
 
 {-
-Note [Minimal complete definition] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Note [Minimal complete definition]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The minimal complete definition should only be included if a complete
 class definition is shown. Since the minimal complete definition is
 anonymous we can't reuse the same mechanism that is used for the
@@ -764,7 +765,7 @@ ppShowIface (ShowSub { ss_how_much = ShowIface }) doc = doc
 ppShowIface _                                     _   = Outputable.empty
 
 -- show if all sub-components or the complete interface is shown
-ppShowAllSubs :: ShowSub -> SDoc -> SDoc -- Note [Minimal complete definition]
+ppShowAllSubs :: ShowSub -> SDoc -> SDoc -- See Note [Minimal complete definition]
 ppShowAllSubs (ShowSub { ss_how_much = ShowSome [] _ }) doc = doc
 ppShowAllSubs (ShowSub { ss_how_much = ShowIface })     doc = doc
 ppShowAllSubs _                                         _   = Outputable.empty
diff --git a/compiler/GHC/Parser/Lexer.x b/compiler/GHC/Parser/Lexer.x
index cb8a1023a3..c92217d0e6 100644
--- a/compiler/GHC/Parser/Lexer.x
+++ b/compiler/GHC/Parser/Lexer.x
@@ -503,7 +503,7 @@ $tab          { warnTab }
 -- when trying to be close to Haskell98
 
 -- Note [Lexing NumericUnderscores extension] (#14473)
---
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -- NumericUnderscores extension allows underscores in numeric literals.
 -- Multiple underscores are represented with @numspc macro.
 -- To be simpler, we have only the definitions with underscores.
diff --git a/compiler/GHC/Rename/Expr.hs b/compiler/GHC/Rename/Expr.hs
index ac0de6b772..148d401f91 100644
--- a/compiler/GHC/Rename/Expr.hs
+++ b/compiler/GHC/Rename/Expr.hs
@@ -2175,7 +2175,7 @@ segments stmts = map fst $ merge $ reverse $ map reverse $ walk (reverse stmts)
 
 {-
 Note [ApplicativeDo and strict patterns]
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A strict pattern match is really a dependency.  For example,
 
 do
@@ -2230,7 +2230,7 @@ isStrictPattern (L loc pat) =
 
 {-
 Note [ApplicativeDo and refutable patterns]
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Refutable patterns in do blocks are desugared to use the monadic 'fail' operation.
 This means that sometimes an applicative block needs to be wrapped in 'join' simply because
 of a refutable pattern, in order for the types to work out.
diff --git a/compiler/GHC/Tc/Gen/Bind.hs b/compiler/GHC/Tc/Gen/Bind.hs
index 04ff88f7b9..4c5fa5aaa8 100644
--- a/compiler/GHC/Tc/Gen/Bind.hs
+++ b/compiler/GHC/Tc/Gen/Bind.hs
@@ -1381,7 +1381,7 @@ tcLhs sig_fn no_gen (PatBind { pat_lhs = pat, pat_rhs = grhss })
                              [ (mbi_poly_name mbi, mbi_mono_id mbi)
                              | mbi <- sig_mbis ]
 
-            -- See Note [Existentials in pattern bindings]
+            -- See Note [Typechecking pattern bindings]
         ; ((pat', nosig_mbis), pat_ty)
             <- addErrCtxt (patMonoBindsCtxt pat grhss) $
                tcInferFRR FRRPatBind $ \ exp_ty ->
diff --git a/compiler/GHC/Tc/Gen/Export.hs b/compiler/GHC/Tc/Gen/Export.hs
index 47be72763a..27b2e84d6a 100644
--- a/compiler/GHC/Tc/Gen/Export.hs
+++ b/compiler/GHC/Tc/Gen/Export.hs
@@ -421,8 +421,7 @@ classifyGREs = partitionGreNames . map gre_name
 
 {-
 Note [Modules without a module header]
---------------------------------------------------
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The Haskell 2010 report says in section 5.1:
 
 >> An abbreviated form of module, consisting only of the module body, is
@@ -523,7 +522,8 @@ lookupChildrenExport spec_parent rdr_items =
             IncorrectParent p c gs -> failWithDcErr p c gs
 
 
--- Note: [Typing Pattern Synonym Exports]
+-- Note [Typing Pattern Synonym Exports]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -- It proved quite a challenge to precisely specify which pattern synonyms
 -- should be allowed to be bundled with which type constructors.
 -- In the end it was decided to be quite liberal in what we allow. Below is
@@ -567,8 +567,8 @@ lookupChildrenExport spec_parent rdr_items =
 --    type constructor.
 --
 --
--- Note: [Types of TyCon]
---
+-- Note [Types of TyCon]
+-- ~~~~~~~~~~~~~~~~~~~~~
 -- This check appears to be overly complicated, Richard asked why it
 -- is not simply just `isAlgTyCon`. The answer for this is that
 -- a classTyCon is also an `AlgTyCon` which we explicitly want to disallow.
diff --git a/compiler/GHC/Tc/Gen/Expr.hs b/compiler/GHC/Tc/Gen/Expr.hs
index f85cf4ade5..492c46c7df 100644
--- a/compiler/GHC/Tc/Gen/Expr.hs
+++ b/compiler/GHC/Tc/Gen/Expr.hs
@@ -676,7 +676,7 @@ tcExpr expr@(RecordUpd { rupd_expr = record_expr, rupd_flds = Left rbnds }) res_
                            not (isRecordSelector sel_id),
                            let fld_name = idName sel_id ]
         ; unless (null bad_guys) (sequence bad_guys >> failM)
-        -- See Note [Mixed Record Selectors]
+        -- See Note [Mixed Record Field Updates]
         ; let (data_sels, pat_syn_sels) =
                 partition isDataConRecordSelector sel_ids
         ; massert (all isPatSynRecordSelector pat_syn_sels)
diff --git a/compiler/GHC/Tc/Module.hs b/compiler/GHC/Tc/Module.hs
index 9a19461b13..c11639725e 100644
--- a/compiler/GHC/Tc/Module.hs
+++ b/compiler/GHC/Tc/Module.hs
@@ -1913,7 +1913,7 @@ generateMainBinding tcg_env main_name = do
     ; (ev_binds, main_expr) <- setMainCtxt main_name io_ty $
                                tcCheckMonoExpr main_expr_rn io_ty
 
-            -- See Note [Root-main id]
+            -- See Note [Root-main Id]
             -- Construct the binding
             --      :Main.main :: IO res_ty = runMainIO res_ty main
     ; run_main_id <- tcLookupId runMainIOName
@@ -1983,7 +1983,7 @@ the moving parts:
   - check that the export list does indeed export something called 'foo'
   - generateMainBinding: generate the root-main binding
        :Main.main = runMainIO M.foo
-  See Note [Root-main id]
+  See Note [Root-main Id]
 
 An annoying consequence of having both checkMainType and checkMain is
 that, when (but only when) -fdefer-type-errors is on, we may report an
diff --git a/compiler/GHC/Tc/Solver/Interact.hs b/compiler/GHC/Tc/Solver/Interact.hs
index 0a246939c6..5adccd835c 100644
--- a/compiler/GHC/Tc/Solver/Interact.hs
+++ b/compiler/GHC/Tc/Solver/Interact.hs
@@ -2294,7 +2294,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 types story] in GHC.Builtin.Types.Prim.
 naturallyCoherentClass :: Class -> Bool
 naturallyCoherentClass cls
   = isCTupleClass cls
diff --git a/compiler/GHC/Tc/TyCl.hs b/compiler/GHC/Tc/TyCl.hs
index 302f93e691..604740c657 100644
--- a/compiler/GHC/Tc/TyCl.hs
+++ b/compiler/GHC/Tc/TyCl.hs
@@ -4359,7 +4359,7 @@ checkValidDataCon dflags existential_ok tc con
         -- matches the type constructor; eg reject this:
         --   data T a where { MkT :: Bogus a }
         -- It's important to do this first:
-        --  see Note [rejigCon
+        --  see Note [rejigConRes]
         --  and c.f. Note [Check role annotations in a second pass]
 
         -- Check that the return type of the data constructor is an instance
diff --git a/compiler/GHC/Tc/Utils/Env.hs b/compiler/GHC/Tc/Utils/Env.hs
index 993f458731..b116cbbb29 100644
--- a/compiler/GHC/Tc/Utils/Env.hs
+++ b/compiler/GHC/Tc/Utils/Env.hs
@@ -1139,7 +1139,7 @@ mkWrapperName wrapperRef what nameBase
 
 {-
 Note [Generating fresh names for FFI wrappers]
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 We used to use a unique, rather than nextWrapperNum, to distinguish
 between FFI wrapper functions. However, the wrapper names that we
 generate are external names. This means that if a call to them ends up
diff --git a/compiler/GHC/Types/Basic.hs b/compiler/GHC/Types/Basic.hs
index a843250de7..92bb8241dd 100644
--- a/compiler/GHC/Types/Basic.hs
+++ b/compiler/GHC/Types/Basic.hs
@@ -1367,7 +1367,7 @@ isAlwaysActive AlwaysActive = True
 isAlwaysActive _            = False
 
 competesWith :: Activation -> Activation -> Bool
--- See Note [Activation competition]
+-- See Note [Competing activations]
 competesWith AlwaysActive      _                = True
 
 competesWith NeverActive       _                = False
diff --git a/compiler/GHC/Types/Error.hs b/compiler/GHC/Types/Error.hs
index 2509c25446..aab0bbf0e8 100644
--- a/compiler/GHC/Types/Error.hs
+++ b/compiler/GHC/Types/Error.hs
@@ -355,8 +355,9 @@ data MessageClass
     -- emitting compiler diagnostics, use the smart constructor.
   deriving (Eq, Show)
 
-{- Note [Suppressing Messages]
-
+{-
+Note [Suppressing Messages]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'SevIgnore' constructor is used to generate messages for diagnostics which
 are meant to be suppressed and not reported to the user: the classic example
 are warnings for which the user didn't enable the corresponding 'WarningFlag',
diff --git a/compiler/GHC/Utils/Monad.hs b/compiler/GHC/Utils/Monad.hs
index 59964b8024..1a4ddae504 100644
--- a/compiler/GHC/Utils/Monad.hs
+++ b/compiler/GHC/Utils/Monad.hs
@@ -355,8 +355,8 @@ function might be required. For example in FCode we use:
       where
         FCode m = FCode' $ oneShot (\cgInfoDown -> oneShot (\state ->m cgInfoDown state))
 
-INLINE pragmas and (>>)
-~~~~~~~~~~~~~~~~~~~~~~~
+Note [INLINE pragmas and (>>)]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A nasty gotcha is described in #20008.  In brief, be careful if you get (>>) via
 its default method: