Fix all invalid haddock comments in the compiler

Fixes #20935 and #20924

41 files changed, 154 insertions, 154 deletions

diff --git a/compiler/GHC/Cmm/Dataflow.hs b/compiler/GHC/Cmm/Dataflow.hs
index ad1c37ace2..edd91481e7 100644
--- a/compiler/GHC/Cmm/Dataflow.hs
+++ b/compiler/GHC/Cmm/Dataflow.hs
@@ -151,8 +151,8 @@ fixpointAnalysis direction lattice do_block entry blockmap = loop start
     join       = fact_join lattice
 
     loop
-        :: IntHeap     -- ^ Worklist, i.e., blocks to process
-        -> FactBase f  -- ^ Current result (increases monotonically)
+        :: IntHeap     -- Worklist, i.e., blocks to process
+        -> FactBase f  -- Current result (increases monotonically)
         -> FactBase f
     loop todo !fbase1 | Just (index, todo1) <- IntSet.minView todo =
         let block = block_arr ! index
@@ -218,9 +218,9 @@ fixpointRewrite dir lattice do_block entry blockmap = loop start blockmap
     join       = fact_join lattice
 
     loop
-        :: IntHeap            -- ^ Worklist, i.e., blocks to process
-        -> LabelMap (Block node C C)  -- ^ Rewritten blocks.
-        -> FactBase f         -- ^ Current facts.
+        :: IntHeap                    -- Worklist, i.e., blocks to process
+        -> LabelMap (Block node C C)  -- Rewritten blocks.
+        -> FactBase f                 -- Current facts.
         -> UniqSM (LabelMap (Block node C C), FactBase f)
     loop todo !blocks1 !fbase1
       | Just (index, todo1) <- IntSet.minView todo = do
diff --git a/compiler/GHC/Cmm/Dataflow/Graph.hs b/compiler/GHC/Cmm/Dataflow/Graph.hs
index 3fbdae85ec..953ccdabaa 100644
--- a/compiler/GHC/Cmm/Dataflow/Graph.hs
+++ b/compiler/GHC/Cmm/Dataflow/Graph.hs
@@ -154,13 +154,13 @@ revPostorderFrom graph start = go start_worklist setEmpty []
   where
     start_worklist = lookup_for_descend start Nil
 
-    -- To compute the postorder we need to "visit" a block (mark as done)
-    -- *after* visiting all its successors. So we need to know whether we
-    -- already processed all successors of each block (and @NonLocal@ allows
-    -- arbitrary many successors). So we use an explicit stack with an extra bit
+    -- To compute the postorder we need to "visit" a block (mark as done) *after*
+    -- visiting all its successors. So we need to know whether we already
+    -- processed all successors of each block (and @NonLocal@ allows arbitrary
+    -- many successors). So we use an explicit stack with an extra bit
     -- of information:
-    -- * @ConsTodo@ means to explore the block if it wasn't visited before
-    -- * @ConsMark@ means that all successors were already done and we can add
+    -- - @ConsTodo@ means to explore the block if it wasn't visited before
+    -- - @ConsMark@ means that all successors were already done and we can add
     --   the block to the result.
     --
     -- NOTE: We add blocks to the result list in postorder, but we *prepend*
diff --git a/compiler/GHC/Cmm/ProcPoint.hs b/compiler/GHC/Cmm/ProcPoint.hs
index cd55b4d255..9297a25378 100644
--- a/compiler/GHC/Cmm/ProcPoint.hs
+++ b/compiler/GHC/Cmm/ProcPoint.hs
@@ -213,7 +213,7 @@ extendPPSet platform g blocks procPoints =
                                 ProcPoint -> 1
                                 ReachedBy ps -> setSize ps
                 block_procpoints = nreached (entryLabel b)
-                -- | Looking for a successor of b that is reached by
+                -- Looking for a successor of b that is reached by
                 -- more proc points than b and is not already a proc
                 -- point.  If found, it can become a proc point.
                 newId succ_id = not (setMember succ_id procPoints') &&
diff --git a/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs b/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs
index 1f1ff9ebc0..862eea721c 100644
--- a/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs
+++ b/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs
@@ -200,7 +200,7 @@ ann doc instr {- debugIsOn -} = ANN doc instr
 -- never end up being forced.
 annExpr :: CmmExpr -> Instr -> Instr
 annExpr e instr {- debugIsOn -} = ANN (text . show $ e) instr
--- annExpr e instr {- | debugIsOn -} = ANN (pprExpr genericPlatform e) instr
+-- annExpr e instr {- debugIsOn -} = ANN (pprExpr genericPlatform e) instr
 -- annExpr _ instr = instr
 {-# INLINE annExpr #-}
 
diff --git a/compiler/GHC/CmmToAsm/CFG.hs b/compiler/GHC/CmmToAsm/CFG.hs
index 0a662d7ff9..8f8b71b1f7 100644
--- a/compiler/GHC/CmmToAsm/CFG.hs
+++ b/compiler/GHC/CmmToAsm/CFG.hs
@@ -712,7 +712,7 @@ optHsPatterns weights (CmmProc info _lab _live graph) cfg =
     increaseBackEdgeWeight (g_entry graph) $ cfg
   where
 
-    -- | Increase the weight of all backedges in the CFG
+    -- Increase the weight of all backedges in the CFG
     -- this helps to make loop jumpbacks the heaviest edges
     increaseBackEdgeWeight :: BlockId -> CFG -> CFG
     increaseBackEdgeWeight root cfg =
@@ -725,7 +725,7 @@ optHsPatterns weights (CmmProc info _lab _live graph) cfg =
         in  foldl'  (\cfg edge -> updateEdgeWeight update edge cfg)
                     cfg backedges
 
-    -- | Since we cant fall through info tables we penalize these.
+    -- Since we cant fall through info tables we penalize these.
     penalizeInfoTables :: LabelMap a -> CFG -> CFG
     penalizeInfoTables info cfg =
         mapWeights fupdate cfg
@@ -736,7 +736,7 @@ optHsPatterns weights (CmmProc info _lab _live graph) cfg =
           = weight - (fromIntegral $ infoTablePenalty weights)
           | otherwise = weight
 
-    -- | If a block has two successors, favour the one with fewer
+    -- If a block has two successors, favour the one with fewer
     -- predecessors and/or the one allowing fall through.
     favourFewerPreds :: CFG -> CFG
     favourFewerPreds cfg =
diff --git a/compiler/GHC/CmmToAsm/Dwarf.hs b/compiler/GHC/CmmToAsm/Dwarf.hs
index 07ca55d6d8..503aca0b3e 100644
--- a/compiler/GHC/CmmToAsm/Dwarf.hs
+++ b/compiler/GHC/CmmToAsm/Dwarf.hs
@@ -245,7 +245,7 @@ procToFrame initUws blk
           where uws'   = addDefaultUnwindings initUws uws
                 nested = concatMap flatten blocks
 
-        -- | If the current procedure has an info table, then we also say that
+        -- If the current procedure has an info table, then we also say that
         -- its first block has one to ensure that it gets the necessary -1
         -- offset applied to its start address.
         -- See Note [Info Offset] in "GHC.CmmToAsm.Dwarf.Types".
diff --git a/compiler/GHC/CmmToAsm/Reg/Linear.hs b/compiler/GHC/CmmToAsm/Reg/Linear.hs
index 53d0a212c3..708290372d 100644
--- a/compiler/GHC/CmmToAsm/Reg/Linear.hs
+++ b/compiler/GHC/CmmToAsm/Reg/Linear.hs
@@ -385,9 +385,9 @@ linearRA
                 , [NatBasicBlock instr])        --   fresh blocks of fixup code.
 linearRA block_live block_id = go [] []
   where
-    go :: [instr]                              -- ^ accumulator for instructions already processed.
-       -> [NatBasicBlock instr]                -- ^ accumulator for blocks of fixup code.
-       -> [LiveInstr instr]                    -- ^ liveness annotated instructions in this block.
+    go :: [instr]                              -- accumulator for instructions already processed.
+       -> [NatBasicBlock instr]                -- accumulator for blocks of fixup code.
+       -> [LiveInstr instr]                    -- liveness annotated instructions in this block.
        -> RegM freeRegs
                ( [instr]                       --   instructions after register allocation
                , [NatBasicBlock instr] )       --   fresh blocks of fixup code.
diff --git a/compiler/GHC/CmmToLlvm/CodeGen.hs b/compiler/GHC/CmmToLlvm/CodeGen.hs
index 3b7ca1ebbe..f44fe1af6e 100644
--- a/compiler/GHC/CmmToLlvm/CodeGen.hs
+++ b/compiler/GHC/CmmToLlvm/CodeGen.hs
@@ -1738,7 +1738,7 @@ genMachOp_slow opt op [x, y] = case op of
               [vx',vy'] -> doExprW ty $ binOp vx' vy'
               _         -> panic "genMachOp_slow: binCastLlvmOp"
 
-        -- | Need to use EOption here as Cmm expects word size results from
+        -- Need to use EOption here as Cmm expects word size results from
         -- comparisons while LLVM return i1. Need to extend to llvmWord type
         -- if expected. See Note [Literals and branch conditions].
         genBinComp opt cmp = do
@@ -1761,7 +1761,7 @@ genMachOp_slow opt op [x, y] = case op of
 
         genCastBinMach ty op = binCastLlvmOp ty (LlvmOp op)
 
-        -- | Detect if overflow will occur in signed multiply of the two
+        -- Detect if overflow will occur in signed multiply of the two
         -- CmmExpr's. This is the LLVM assembly equivalent of the NCG
         -- implementation. Its much longer due to type information/safety.
         -- This should actually compile to only about 3 asm instructions.
diff --git a/compiler/GHC/Core/Lint.hs b/compiler/GHC/Core/Lint.hs
index b9ca990f3d..6390d83b1e 100644
--- a/compiler/GHC/Core/Lint.hs
+++ b/compiler/GHC/Core/Lint.hs
@@ -1119,9 +1119,9 @@ checkCanEtaExpand (Var fun_id) args app_ty
       check_args :: [Type] -> [Type]
       check_args = go (nb_val_args + 1)
         where
-          go :: Int    -- ^ index of the argument (starting from 1)
-             -> [Type] -- ^ arguments
-             -> [Type] -- ^ value argument types that could not be
+          go :: Int    -- index of the argument (starting from 1)
+             -> [Type] -- arguments
+             -> [Type] -- value argument types that could not be
                        -- determined to have a fixed runtime representation
           go i _
             | i > arity
diff --git a/compiler/GHC/Core/Opt/DmdAnal.hs b/compiler/GHC/Core/Opt/DmdAnal.hs
index 347cc4228d..945af5ea9e 100644
--- a/compiler/GHC/Core/Opt/DmdAnal.hs
+++ b/compiler/GHC/Core/Opt/DmdAnal.hs
@@ -97,7 +97,7 @@ dmdAnalProgram opts fam_envs rules binds
     add_exported_uses :: AnalEnv -> DmdType -> [Id] -> DmdType
     add_exported_uses env = foldl' (add_exported_use env)
 
-    -- | If @e@ is denoted by @dmd_ty@, then @add_exported_use _ dmd_ty id@
+    -- If @e@ is denoted by @dmd_ty@, then @add_exported_use _ dmd_ty id@
     -- corresponds to the demand type of @(id, e)@, but is a lot more direct.
     -- See Note [Analysing top-level bindings].
     add_exported_use :: AnalEnv -> DmdType -> Id -> DmdType
@@ -959,7 +959,7 @@ unboxedWhenSmall :: AnalEnv -> RecFlag -> Maybe Type -> SubDemand -> SubDemand
 unboxedWhenSmall _   _        Nothing       sd = sd
 unboxedWhenSmall env rec_flag (Just ret_ty) sd = go 1 ret_ty sd
   where
-    -- | Magic constant, bounding the depth of optimistic 'Unboxed' flags. We
+    -- Magic constant, bounding the depth of optimistic 'Unboxed' flags. We
     -- might want to minmax in the future.
     max_depth | isRec rec_flag = 3 -- So we get at most something as deep as !P(L!P(L!L))
               | otherwise      = 1 -- Otherwise be unbox too deep in T18109, T18174 and others and get a bunch of stack overflows
diff --git a/compiler/GHC/Core/Opt/Exitify.hs b/compiler/GHC/Core/Opt/Exitify.hs
index 164d7119f4..ac4df91f97 100644
--- a/compiler/GHC/Core/Opt/Exitify.hs
+++ b/compiler/GHC/Core/Opt/Exitify.hs
@@ -131,11 +131,11 @@ exitifyRec in_scope pairs
     -- variables bound on the way and lifts it out as a join point.
     --
     -- ExitifyM is a state monad to keep track of floated binds
-    go :: [Var]           -- ^ Variables that are in-scope here, but
+    go :: [Var]           -- Variables that are in-scope here, but
                           -- not in scope at the joinrec; that is,
                           -- we must potentially abstract over them.
                           -- Invariant: they are kept in dependency order
-       -> CoreExprWithFVs -- ^ Current expression in tail position
+       -> CoreExprWithFVs -- Current expression in tail position
        -> ExitifyM CoreExpr
 
     -- We first look at the expression (no matter what it shape is)
diff --git a/compiler/GHC/Core/Opt/SpecConstr.hs b/compiler/GHC/Core/Opt/SpecConstr.hs
index a5579108e6..90f492ffea 100644
--- a/compiler/GHC/Core/Opt/SpecConstr.hs
+++ b/compiler/GHC/Core/Opt/SpecConstr.hs
@@ -2454,7 +2454,7 @@ argToPat1 _env _in_scope _val_env arg _arg_occ arg_str
 setStrUnfolding :: Id -> StrictnessMark  -> Id
 -- setStrUnfolding id str = id
 setStrUnfolding id str
-  -- | pprTrace "setStrUnfolding"
+  -- pprTrace "setStrUnfolding"
   --   (ppr id <+> ppr (isMarkedCbv str) $$
   --    ppr (idType id) $$
   --    text "boxed:" <> ppr (isBoxedType (idType id)) $$
diff --git a/compiler/GHC/Core/Opt/WorkWrap.hs b/compiler/GHC/Core/Opt/WorkWrap.hs
index a6e583a210..93c4c31995 100644
--- a/compiler/GHC/Core/Opt/WorkWrap.hs
+++ b/compiler/GHC/Core/Opt/WorkWrap.hs
@@ -556,15 +556,15 @@ tryWW ww_opts is_rec fn_id rhs
   -- CPR information in GHC.Core.Opt.CprAnal.cprAnalBind, it actually
   -- isn't. That is because we would still perform w/w when:
   --
-  -- * An argument is used strictly, and -fworker-wrapper-cbv is
+  -- - An argument is used strictly, and -fworker-wrapper-cbv is
   --   enabled, or,
-  -- * When demand analysis marks an argument as absent.
+  -- - When demand analysis marks an argument as absent.
   --
   -- In a debug build we do assert that boxity and CPR information
   -- are actually stripped, since we want to prevent callers of OPAQUE
   -- things to do reboxing. See:
-  -- * Note [The OPAQUE pragma and avoiding the reboxing of arguments]
-  -- * Note [The OPAQUE pragma and avoiding the reboxing of results]
+  -- - Note [The OPAQUE pragma and avoiding the reboxing of arguments]
+  -- - Note [The OPAQUE pragma and avoiding the reboxing of results]
   | isOpaquePragma (inlinePragInfo fn_info)
   = assertPpr (onlyBoxedArguments (dmdSigInfo fn_info) &&
                isTopCprSig (cprSigInfo fn_info))
diff --git a/compiler/GHC/Core/Opt/WorkWrap/Utils.hs b/compiler/GHC/Core/Opt/WorkWrap/Utils.hs
index 298bb3202a..6bb751d803 100644
--- a/compiler/GHC/Core/Opt/WorkWrap/Utils.hs
+++ b/compiler/GHC/Core/Opt/WorkWrap/Utils.hs
@@ -661,7 +661,7 @@ wantToUnboxResult fam_envs ty cpr
   = StopUnboxing
 
   where
-    -- | See Note [non-algebraic or open body type warning]
+    -- See Note [non-algebraic or open body type warning]
     open_body_ty_warning = warnPprTrace True "wantToUnboxResult: non-algebraic or open body type" (ppr ty) Nothing
 
 isLinear :: Scaled a -> Bool
@@ -1296,8 +1296,7 @@ isRecDataCon fam_envs fuel orig_dc
     go_tc_app :: IntWithInf -> TyConSet -> TyCon -> [Type] -> IsRecDataConResult
     go_tc_app fuel visited_tcs tc tc_args =
       case tyConDataCons_maybe tc of
-        --- | pprTrace "tc_app" (vcat [ppr tc, ppr tc_args]) False -> undefined
-
+      --- | pprTrace "tc_app" (vcat [ppr tc, ppr tc_args]) False = undefined
         _ | Just (HetReduction (Reduction _ rhs) _) <- topReduceTyFamApp_maybe fam_envs tc tc_args
           -- This is the only place where we look at tc_args, which might have
           -- See Note [Detecting recursive data constructors], point (C) and (5)
diff --git a/compiler/GHC/Core/Utils.hs b/compiler/GHC/Core/Utils.hs
index da13a346d8..5100f958e6 100644
--- a/compiler/GHC/Core/Utils.hs
+++ b/compiler/GHC/Core/Utils.hs
@@ -332,9 +332,9 @@ mkTick t orig_expr = mkTick' id id orig_expr
   -- non-counting part having laxer placement properties.
   canSplit = tickishCanSplit t && tickishPlace (mkNoCount t) /= tickishPlace t
 
-  mkTick' :: (CoreExpr -> CoreExpr) -- ^ apply after adding tick (float through)
-          -> (CoreExpr -> CoreExpr) -- ^ apply before adding tick (float with)
-          -> CoreExpr               -- ^ current expression
+  mkTick' :: (CoreExpr -> CoreExpr) -- apply after adding tick (float through)
+          -> (CoreExpr -> CoreExpr) -- apply before adding tick (float with)
+          -> CoreExpr               -- current expression
           -> CoreExpr
   mkTick' top rest expr = case expr of
 
diff --git a/compiler/GHC/CoreToStg/Prep.hs b/compiler/GHC/CoreToStg/Prep.hs
index b8593b47a0..fa9496b4c5 100644
--- a/compiler/GHC/CoreToStg/Prep.hs
+++ b/compiler/GHC/CoreToStg/Prep.hs
@@ -1136,7 +1136,7 @@ cpeApp top_env expr
            ; (app, floats,unsat_ticks) <- rebuild_app env args fun' fun_floats [] Nothing
            ; mb_saturate Nothing app floats unsat_ticks (val_args args) }
 
-    -- | Count the number of value arguments.
+    -- Count the number of value arguments.
     val_args :: [ArgInfo] -> Int
     val_args args = go args 0
       where
diff --git a/compiler/GHC/Data/Graph/Color.hs b/compiler/GHC/Data/Graph/Color.hs
index 0e96b5da01..452da2dbe9 100644
--- a/compiler/GHC/Data/Graph/Color.hs
+++ b/compiler/GHC/Data/Graph/Color.hs
@@ -268,9 +268,9 @@ assignColors
 assignColors colors graph ks
         = assignColors' colors graph [] ks
 
- where  assignColors' :: UniqFM cls (UniqSet color)       -- ^ map of (node class -> set of colors available for this class).
-                        -> Graph k cls color            -- ^ the graph
-                        -> [k]                          -- ^ nodes to assign a color to.
+ where  assignColors' :: UniqFM cls (UniqSet color)     -- map of (node class -> set of colors available for this class).
+                        -> Graph k cls color            -- the graph
+                        -> [k]                          -- nodes to assign a color to.
                         -> [k]
                         -> ( Graph k cls color          -- the colored graph
                         , [k])
@@ -303,9 +303,9 @@ assignColors colors graph ks
 selectColor
         :: ( Uniquable k, Uniquable cls, Uniquable color
            , Outputable cls)
-        => UniqFM cls (UniqSet color)       -- ^ map of (node class -> set of colors available for this class).
-        -> Graph k cls color            -- ^ the graph
-        -> k                            -- ^ key of the node to select a color for.
+        => UniqFM cls (UniqSet color)   -- map of (node class -> set of colors available for this class).
+        -> Graph k cls color            -- the graph
+        -> k                            -- key of the node to select a color for.
         -> Maybe color
 
 selectColor colors graph u
diff --git a/compiler/GHC/Driver/Main.hs b/compiler/GHC/Driver/Main.hs
index 32b94fbf14..4c17228852 100644
--- a/compiler/GHC/Driver/Main.hs
+++ b/compiler/GHC/Driver/Main.hs
@@ -1438,7 +1438,7 @@ hscCheckSafe' m l = do
                       $ mkErrorMsgEnvelope l (pkgQual state)
                       $ GhcDriverMessage $ DriverCannotImportUnsafeModule m
 
-    -- | Check the package a module resides in is trusted. Safe compiled
+    -- Check the package a module resides in is trusted. Safe compiled
     -- modules are trusted without requiring that their package is trusted. For
     -- trustworthy modules, modules in the home package are trusted but
     -- otherwise we check the package trust flag.
diff --git a/compiler/GHC/Hs.hs b/compiler/GHC/Hs.hs
index b0eb32b380..5a6f2cc2be 100644
--- a/compiler/GHC/Hs.hs
+++ b/compiler/GHC/Hs.hs
@@ -68,7 +68,16 @@ import Data.Data hiding ( Fixity )
 --
 -- All we actually declare here is the top-level structure for a module.
 data HsModule
-  = HsModule {
+  =  -- | 'GHC.Parser.Annotation.AnnKeywordId's
+     --
+     --  - 'GHC.Parser.Annotation.AnnModule','GHC.Parser.Annotation.AnnWhere'
+     --
+     --  - 'GHC.Parser.Annotation.AnnOpen','GHC.Parser.Annotation.AnnSemi',
+     --    'GHC.Parser.Annotation.AnnClose' for explicit braces and semi around
+     --    hsmodImports,hsmodDecls if this style is used.
+
+     -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
+    HsModule {
       hsmodAnn :: EpAnn AnnsModule,
       hsmodLayout :: LayoutInfo,
         -- ^ Layout info for the module.
@@ -112,15 +121,6 @@ data HsModule
 
         -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
    }
-     -- ^ 'GHC.Parser.Annotation.AnnKeywordId's
-     --
-     --  - 'GHC.Parser.Annotation.AnnModule','GHC.Parser.Annotation.AnnWhere'
-     --
-     --  - 'GHC.Parser.Annotation.AnnOpen','GHC.Parser.Annotation.AnnSemi',
-     --    'GHC.Parser.Annotation.AnnClose' for explicit braces and semi around
-     --    hsmodImports,hsmodDecls if this style is used.
-
-     -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
 
 deriving instance Data HsModule
 
diff --git a/compiler/GHC/Hs/Binds.hs b/compiler/GHC/Hs/Binds.hs
index d67d1c4312..3a22863537 100644
--- a/compiler/GHC/Hs/Binds.hs
+++ b/compiler/GHC/Hs/Binds.hs
@@ -91,27 +91,28 @@ type instance XXValBindsLR (GhcPass pL) pR
 
 type instance XFunBind    (GhcPass pL) GhcPs = NoExtField
 type instance XFunBind    (GhcPass pL) GhcRn = NameSet
-          -- ^ After the renamer (but before the type-checker), the FunBind
-          -- extension field contains the locally-bound free variables of this
-          -- defn. See Note [Bind free vars]
+-- ^ After the renamer (but before the type-checker), the FunBind
+-- extension field contains the locally-bound free variables of this
+-- defn. See Note [Bind free vars]
+
 type instance XFunBind    (GhcPass pL) GhcTc = HsWrapper
-          -- ^ After the type-checker, the FunBind extension field contains a
-          -- coercion from the type of the MatchGroup to the type of the Id.
-          -- Example:
-          --
-          -- @
-          --      f :: Int -> forall a. a -> a
-          --      f x y = y
-          -- @
-          --
-          -- Then the MatchGroup will have type (Int -> a' -> a')
-          -- (with a free type variable a').  The coercion will take
-          -- a CoreExpr of this type and convert it to a CoreExpr of
-          -- type         Int -> forall a'. a' -> a'
-          -- Notice that the coercion captures the free a'.
+-- ^ After the type-checker, the FunBind extension field contains a
+-- coercion from the type of the MatchGroup to the type of the Id.
+-- Example:
+--
+-- @
+--      f :: Int -> forall a. a -> a
+--      f x y = y
+-- @
+--
+-- Then the MatchGroup will have type (Int -> a' -> a')
+-- (with a free type variable a').  The coercion will take
+-- a CoreExpr of this type and convert it to a CoreExpr of
+-- type         Int -> forall a'. a' -> a'
+-- Notice that the coercion captures the free a'.
 
 type instance XPatBind    GhcPs (GhcPass pR) = EpAnn [AddEpAnn]
-type instance XPatBind    GhcRn (GhcPass pR) = NameSet -- ^ See Note [Bind free vars]
+type instance XPatBind    GhcRn (GhcPass pR) = NameSet -- See Note [Bind free vars]
 type instance XPatBind    GhcTc (GhcPass pR) = Type    -- Type of the GRHSs
 
 type instance XVarBind    (GhcPass pL) (GhcPass pR) = NoExtField
@@ -122,7 +123,7 @@ type instance XXHsBindsLR GhcRn pR = DataConCantHappen
 type instance XXHsBindsLR GhcTc pR = AbsBinds
 
 type instance XPSB         (GhcPass idL) GhcPs = EpAnn [AddEpAnn]
-type instance XPSB         (GhcPass idL) GhcRn = NameSet -- ^ Post renaming, FVs. See Note [Bind free vars]
+type instance XPSB         (GhcPass idL) GhcRn = NameSet -- Post renaming, FVs. See Note [Bind free vars]
 type instance XPSB         (GhcPass idL) GhcTc = NameSet
 
 type instance XXPatSynBind (GhcPass idL) (GhcPass idR) = DataConCantHappen
diff --git a/compiler/GHC/Hs/Pat.hs b/compiler/GHC/Hs/Pat.hs
index c81018da40..9ca56e3290 100644
--- a/compiler/GHC/Hs/Pat.hs
+++ b/compiler/GHC/Hs/Pat.hs
@@ -232,7 +232,7 @@ data ConPatTc
     , -- | Bindings involving those dictionaries
       cpt_binds :: TcEvBinds
 
-    , -- ^ Extra wrapper to pass to the matcher
+    , -- | Extra wrapper to pass to the matcher
       -- Only relevant for pattern-synonyms;
       --   ignored for data cons
       cpt_wrap  :: HsWrapper
diff --git a/compiler/GHC/HsToCore/Pmc/Solver.hs b/compiler/GHC/HsToCore/Pmc/Solver.hs
index 7b0986e6f0..fadd969db8 100644
--- a/compiler/GHC/HsToCore/Pmc/Solver.hs
+++ b/compiler/GHC/HsToCore/Pmc/Solver.hs
@@ -147,7 +147,7 @@ updRcm f (RCM vanilla pragmas)
 -- Ex.: @vanillaCompleteMatchTC 'Maybe' ==> Just ("Maybe", {'Just','Nothing'})@
 vanillaCompleteMatchTC :: TyCon -> Maybe CompleteMatch
 vanillaCompleteMatchTC tc =
-  let -- | TYPE acts like an empty data type on the term-level (#14086), but
+  let -- TYPE acts like an empty data type on the term-level (#14086), but
       -- it is a PrimTyCon, so tyConDataCons_maybe returns Nothing. Hence a
       -- special case.
       mb_dcs | tc == tYPETyCon = Just []
@@ -173,7 +173,7 @@ addConLikeMatches (PatSynCon _)    rcm = addCompleteMatches rcm
 addTyConMatches :: TyCon -> ResidualCompleteMatches -> DsM ResidualCompleteMatches
 addTyConMatches tc rcm = add_tc_match <$> addCompleteMatches rcm
   where
-    -- | Add the vanilla COMPLETE set from the data defn, if any. But only if
+    -- Add the vanilla COMPLETE set from the data defn, if any. But only if
     -- it's not already present.
     add_tc_match rcm
       = rcm{rcm_vanilla = rcm_vanilla rcm <|> vanillaCompleteMatchTC tc}
@@ -722,7 +722,7 @@ addNotConCt nabla x nalt = do
     Just x  -> markDirty x nabla'
     Nothing -> nabla'
   where
-    -- | Update `x`'s 'VarInfo' entry. Fail ('MaybeT') if contradiction,
+    -- Update `x`'s 'VarInfo' entry. Fail ('MaybeT') if contradiction,
     -- otherwise return updated entry and `Just x'` if `x` should be marked dirty,
     -- where `x'` is the representative of `x`.
     go :: VarInfo -> MaybeT DsM (Maybe Id, VarInfo)
@@ -846,7 +846,7 @@ addCoreCt nabla x e = do
   -- lift $ tracePm "addCoreCt" (ppr x <+> dcolon <+> ppr (idType x) $$ ppr e $$ ppr e')
   execStateT (core_expr x e') nabla
   where
-    -- | Takes apart a 'CoreExpr' and tries to extract as much information about
+    -- Takes apart a 'CoreExpr' and tries to extract as much information about
     -- literals and constructor applications as possible.
     core_expr :: Id -> CoreExpr -> StateT Nabla (MaybeT DsM) ()
     -- TODO: Handle newtypes properly, by wrapping the expression in a DataCon
@@ -887,7 +887,7 @@ addCoreCt nabla x e = do
         -- up substituting inside a forall or lambda (i.e. seldom)
         -- so using exprFreeVars seems fine.   See MR !1647.
 
-    -- | The @e@ in @let x = e@ had no familiar form. But we can still see if
+    -- The @e@ in @let x = e@ had no familiar form. But we can still see if
     -- see if we already encountered a constraint @let y = e'@ with @e'@
     -- semantically equivalent to @e@, in which case we may add the constraint
     -- @x ~ y@.
@@ -903,7 +903,7 @@ addCoreCt nabla x e = do
       core_expr x e
       pure x
 
-    -- | Look at @let x = K taus theta es@ and generate the following
+    -- Look at @let x = K taus theta es@ and generate the following
     -- constraints (assuming universals were dropped from @taus@ before):
     --   1. @x ≁ ⊥@ if 'K' is not a Newtype constructor.
     --   2. @a_1 ~ tau_1, ..., a_n ~ tau_n@ for fresh @a_i@
@@ -930,7 +930,7 @@ addCoreCt nabla x e = do
       -- 4. @x ~ K as ys@
       pm_alt_con_app x (PmAltConLike (RealDataCon dc)) ex_tvs arg_ids
 
-    -- | Adds a literal constraint, i.e. @x ~ 42@.
+    -- Adds a literal constraint, i.e. @x ~ 42@.
     -- Also we assume that literal expressions won't diverge, so this
     -- will add a @x ~/ ⊥@ constraint.
     pm_lit :: Id -> PmLit -> StateT Nabla (MaybeT DsM) ()
@@ -938,7 +938,7 @@ addCoreCt nabla x e = do
       modifyT $ \nabla -> addNotBotCt nabla x
       pm_alt_con_app x (PmAltLit lit) [] []
 
-    -- | Adds the given constructor application as a solution for @x@.
+    -- Adds the given constructor application as a solution for @x@.
     pm_alt_con_app :: Id -> PmAltCon -> [TyVar] -> [Id] -> StateT Nabla (MaybeT DsM) ()
     pm_alt_con_app x con tvs args = modifyT $ \nabla -> addConCt nabla x con tvs args
 
@@ -1836,7 +1836,7 @@ generateInhabitingPatterns mode (x:xs) n nabla = do
       | otherwise
       -> generateInhabitingPatterns mode xs n nabla
   where
-    -- | Tries to instantiate a variable by possibly following the chain of
+    -- Tries to instantiate a variable by possibly following the chain of
     -- newtypes and then instantiating to all ConLikes of the wrapped type's
     -- minimal residual COMPLETE set.
     try_instantiate :: Id -> [Id] -> Int -> Nabla -> DsM [Nabla]
@@ -1868,7 +1868,7 @@ generateInhabitingPatterns mode (x:xs) n nabla = do
                 then generateInhabitingPatterns mode xs n newty_nabla -- bot is still possible. Display a wildcard!
                 else pure nablas'
 
-    -- | Instantiates a chain of newtypes, beginning at @x@.
+    -- Instantiates a chain of newtypes, beginning at @x@.
     -- Turns @x nabla [T,U,V]@ to @(y, nabla')@, where @nabla'@ we has the fact
     -- @x ~ T (U (V y))@.
     instantiate_newtype_chain :: Id -> Nabla -> [(Type, DataCon, Type)] -> MaybeT DsM (Id, Nabla)
diff --git a/compiler/GHC/Iface/Ext/Ast.hs b/compiler/GHC/Iface/Ext/Ast.hs
index 73ad2a09b7..db93777a7d 100644
--- a/compiler/GHC/Iface/Ext/Ast.hs
+++ b/compiler/GHC/Iface/Ext/Ast.hs
@@ -725,7 +725,7 @@ instance HiePass p => HasType (LocatedA (HsExpr (GhcPass p))) where
       fallback :: HieM [HieAST Type]
       fallback = makeNodeA e spn
 
-      -- | Skip computing the type of some expressions for performance reasons.
+      -- Skip computing the type of some expressions for performance reasons.
       --
       -- See impact on Haddock output (esp. missing type annotations or links)
       -- before skipping more kinds of expressions. See impact on Haddock
diff --git a/compiler/GHC/Iface/Recomp/Flags.hs b/compiler/GHC/Iface/Recomp/Flags.hs
index b1f6c66e79..e8d13bfa0d 100644
--- a/compiler/GHC/Iface/Recomp/Flags.hs
+++ b/compiler/GHC/Iface/Recomp/Flags.hs
@@ -28,9 +28,8 @@ import System.FilePath (normalise)
 -- the finger print on important fields in @DynFlags@ so that
 -- the recompilation checker can use this fingerprint.
 --
--- NB: The 'Module' parameter is the 'Module' recorded by the
--- *interface* file, not the actual 'Module' according to our
--- 'DynFlags'.
+-- NB: The 'Module' parameter is the 'Module' recorded by the *interface*
+-- file, not the actual 'Module' according to our 'DynFlags'.
 fingerprintDynFlags :: HscEnv -> Module
                     -> (BinHandle -> Name -> IO ())
                     -> IO Fingerprint
@@ -43,7 +42,7 @@ fingerprintDynFlags hsc_env this_mod nameio =
         safeHs   = setSafeMode safeHaskell
         -- oflags   = sort $ filter filterOFlags $ flags dflags
 
-        -- *all* the extension flags and the language
+        -- all the extension flags and the language
         lang = (fmap fromEnum language,
                 map fromEnum $ EnumSet.toList extensionFlags)
 
diff --git a/compiler/GHC/IfaceToCore.hs b/compiler/GHC/IfaceToCore.hs
index 33c9be542e..a248cbf767 100644
--- a/compiler/GHC/IfaceToCore.hs
+++ b/compiler/GHC/IfaceToCore.hs
@@ -603,7 +603,7 @@ mkSelfBootInfo iface mds
        return $ SelfBoot { sb_mds = mds
                          , sb_tcs = mkNameSet tcs }
   where
-    -- | Retuerns @True@ if, when you call 'tcIfaceDecl' on
+    -- Retuerns @True@ if, when you call 'tcIfaceDecl' on
     -- this 'IfaceDecl', an ATyCon would be returned.
     -- NB: This code assumes that a TyCon cannot be implicit.
     isIfaceTyCon IfaceId{}      = False
diff --git a/compiler/GHC/Rename/Expr.hs b/compiler/GHC/Rename/Expr.hs
index f1cb766077..d8b2436dc1 100644
--- a/compiler/GHC/Rename/Expr.hs
+++ b/compiler/GHC/Rename/Expr.hs
@@ -542,7 +542,8 @@ rnExpr e@(HsStatic _ expr) = do
     let fvExpr' = filterNameSet (nameIsLocalOrFrom mod) fvExpr
     return (HsStatic fvExpr' expr', fvExpr)
 
-{- *********************************************************************
+{-
+************************************************************************
 *                                                                      *
         Arrow notation
 *                                                                      *
@@ -557,7 +558,8 @@ rnExpr (HsProc x pat body)
 rnExpr other = pprPanic "rnExpr: unexpected expression" (ppr other)
         -- HsWrap
 
-{- *********************************************************************
+{-
+************************************************************************
 *                                                                      *
         Operator sections
 *                                                                      *
diff --git a/compiler/GHC/Rename/Module.hs b/compiler/GHC/Rename/Module.hs
index 9fbbcacdab..29937ea5f0 100644
--- a/compiler/GHC/Rename/Module.hs
+++ b/compiler/GHC/Rename/Module.hs
@@ -455,7 +455,7 @@ checkCanonicalInstances cls poly_ty mbinds = do
         "https://gitlab.haskell.org/ghc/ghc/-/wikis/proposal/semigroup-monoid"
 
   where
-    -- | Warn about unsound/non-canonical 'Applicative'/'Monad' instance
+    -- Warn about unsound/non-canonical 'Applicative'/'Monad' instance
     -- declarations. Specifically, the following conditions are verified:
     --
     -- In 'Monad' instances declarations:
@@ -501,7 +501,7 @@ checkCanonicalInstances cls poly_ty mbinds = do
 
       | otherwise = return ()
 
-    -- | Check whether Monoid(mappend) is defined in terms of
+    -- Check whether Monoid(mappend) is defined in terms of
     -- Semigroup((<>)) (and not the other way round). Specifically,
     -- the following conditions are verified:
     --
@@ -540,7 +540,7 @@ checkCanonicalInstances cls poly_ty mbinds = do
 
       | otherwise = return ()
 
-    -- | test whether MatchGroup represents a trivial \"lhsName = rhsName\"
+    -- test whether MatchGroup represents a trivial \"lhsName = rhsName\"
     -- binding, and return @Just rhsName@ if this is the case
     isAliasMG :: MatchGroup GhcRn (LHsExpr GhcRn) -> Maybe Name
     isAliasMG MG {mg_alts = (L _ [L _ (Match { m_pats = []
diff --git a/compiler/GHC/Stg/InferTags/Rewrite.hs b/compiler/GHC/Stg/InferTags/Rewrite.hs
index 338d713a7a..1d2d280f2c 100644
--- a/compiler/GHC/Stg/InferTags/Rewrite.hs
+++ b/compiler/GHC/Stg/InferTags/Rewrite.hs
@@ -420,7 +420,7 @@ rewriteApp True (StgApp f []) = do
                 else f
     return $! StgApp f' []
 rewriteApp _ (StgApp f args)
-    -- | pprTrace "rewriteAppOther" (ppr f <+> ppr args) False
+    -- pprTrace "rewriteAppOther" (ppr f <+> ppr args) False
     -- = undefined
     | Just marks <- idCbvMarks_maybe f
     , relevant_marks <- dropWhileEndLE (not . isMarkedCbv) marks
diff --git a/compiler/GHC/StgToCmm/Prim.hs b/compiler/GHC/StgToCmm/Prim.hs
index 4e1e24e93d..b49ad24edd 100644
--- a/compiler/GHC/StgToCmm/Prim.hs
+++ b/compiler/GHC/StgToCmm/Prim.hs
@@ -1661,7 +1661,7 @@ emitPrimOp cfg primop =
     CmmMachOp (mop rep (wordWidth platform)) [CmmMachOp (mop (wordWidth platform) rep) [arg]]
     where [arg] = args
 
-  -- | These primops are implemented by CallishMachOps, because they sometimes
+  -- These primops are implemented by CallishMachOps, because they sometimes
   -- turn into foreign calls depending on the backend.
   opCallish :: [CmmExpr] -> CallishMachOp -> PrimopCmmEmit
   opCallish args prim = opIntoRegs $ \[res] -> emitPrimCall [res] prim args
@@ -1683,7 +1683,7 @@ emitPrimOp cfg primop =
       PW4 -> opCallish args callish
       PW8 -> opTranslate args $ mkMop W64
 
-  -- | Basically a "manual" case, rather than one of the common repetitive forms
+  -- Basically a "manual" case, rather than one of the common repetitive forms
   -- above. The results are a parameter to the returned function so we know the
   -- choice of variant never depends on them.
   opCallishHandledLater
diff --git a/compiler/GHC/Tc/Deriv.hs b/compiler/GHC/Tc/Deriv.hs
index 29a58d9c01..272d7b6d4e 100644
--- a/compiler/GHC/Tc/Deriv.hs
+++ b/compiler/GHC/Tc/Deriv.hs
@@ -247,7 +247,7 @@ tcDeriving deriv_infos deriv_decls
         ; return (addTcgDUs gbl_env all_dus, inst_info, rn_aux_binds) } }
   where
     ddump_deriving :: Bag (InstInfo GhcRn) -> HsValBinds GhcRn
-                   -> [FamInst]               -- ^ Associated type family instances
+                   -> [FamInst]               -- Associated type family instances
                    -> SDoc
     ddump_deriving inst_infos extra_binds famInsts
       =    hang (text "Derived class instances:")
diff --git a/compiler/GHC/Tc/Errors.hs b/compiler/GHC/Tc/Errors.hs
index 2deec2bbd6..9b9eb8077b 100644
--- a/compiler/GHC/Tc/Errors.hs
+++ b/compiler/GHC/Tc/Errors.hs
@@ -403,7 +403,7 @@ warnRedundantConstraints ctxt env info ev_vars
               -- and we don't want to say it twice. Seems a bit ad-hoc
  = report_redundant_msg False
  where
-   report_redundant_msg :: Bool -- ^ whether to add "In ..." to the diagnostic
+   report_redundant_msg :: Bool -- whether to add "In ..." to the diagnostic
                         -> TcRn ()
    report_redundant_msg show_info
      = do { lcl_env <- getLclEnv
diff --git a/compiler/GHC/Tc/Errors/Ppr.hs b/compiler/GHC/Tc/Errors/Ppr.hs
index 29da277c8d..de8d893f80 100644
--- a/compiler/GHC/Tc/Errors/Ppr.hs
+++ b/compiler/GHC/Tc/Errors/Ppr.hs
@@ -526,9 +526,10 @@ instance Diagnostic TcRnMessage where
                                                 quotes (ppr_name child))
                                             2 (pprNameProvenance gre))
 
-        -- DuplicateRecordFields means that nameOccName might be a mangled
-        -- $sel-prefixed thing, in which case show the correct OccName alone
-        -- (but otherwise show the Name so it will have a module qualifier)
+        -- DuplicateRecordFields means that nameOccName might be a
+        -- mangled $sel-prefixed thing, in which case show the correct OccName
+        -- alone (but otherwise show the Name so it will have a module
+        -- qualifier)
         ppr_name (FieldGreName fl) | flIsOverloaded fl = ppr fl
                                    | otherwise         = ppr (flSelector fl)
         ppr_name (NormalGreName name) = ppr name
@@ -2984,8 +2985,8 @@ expandSynonymsToMatch ty1 ty2 = (ty1_ret, ty2_ret)
   where
     (ty1_ret, ty2_ret) = go ty1 ty2
 
-    -- | Returns (type synonym expanded version of first type,
-    --            type synonym expanded version of second type)
+    -- Returns (type synonym expanded version of first type,
+    --          type synonym expanded version of second type)
     go :: Type -> Type -> (Type, Type)
     go t1 t2
       | t1 `pickyEqType` t2 =
@@ -3039,7 +3040,7 @@ expandSynonymsToMatch ty1 ty2 = (ty1_ret, ty2_ret)
             (if t1_exps > t2_exps then drop dif t1_exp_tys else t1_exp_tys)
             (if t2_exps > t1_exps then drop dif t2_exp_tys else t2_exp_tys)
 
-    -- | Expand the top layer type synonyms repeatedly, collect expansions in a
+    -- Expand the top layer type synonyms repeatedly, collect expansions in a
     -- list. The list does not include the original type.
     --
     -- Example, if you have:
@@ -3059,7 +3060,7 @@ expandSynonymsToMatch ty1 ty2 = (ty1_ret, ty2_ret)
     tyExpansions :: Type -> [Type]
     tyExpansions = unfoldr (\t -> (\x -> (x, x)) `fmap` tcView t)
 
-    -- | Drop the type pairs until types in a pair look alike (i.e. the outer
+    -- Drop the type pairs until types in a pair look alike (i.e. the outer
     -- constructors are the same).
     followExpansions :: [(Type, Type)] -> (Type, Type)
     followExpansions [] = pprPanic "followExpansions" empty
diff --git a/compiler/GHC/Tc/Gen/App.hs b/compiler/GHC/Tc/Gen/App.hs
index 743587ed25..c2df311b30 100644
--- a/compiler/GHC/Tc/Gen/App.hs
+++ b/compiler/GHC/Tc/Gen/App.hs
@@ -569,11 +569,11 @@ hasFixedRuntimeRep_remainingValArgs applied_args app_res_rho = \case
       traceTc "tcApp remainingValArgs check_thing" (debug_msg thing arity)
       go (nb_applied_vis_val_args + 1) (nb_applied_val_args + 1) arg_tys
       where
-        go :: Int -- ^ visible value argument index, starting from 1
+        go :: Int -- visible value argument index, starting from 1
                   -- only used to report the argument position in error messages
-           -> Int -- ^ value argument index, starting from 1
+           -> Int -- value argument index, starting from 1
                   -- used to count up to the arity to ensure we don't check too many argument types
-           -> [(Type, AnonArgFlag)] -- ^ run-time argument types
+           -> [(Type, AnonArgFlag)] -- run-time argument types
            -> TcM ()
         go _ i_val _
           | i_val > arity
diff --git a/compiler/GHC/Tc/Gen/Export.hs b/compiler/GHC/Tc/Gen/Export.hs
index 26b765a9d1..47be72763a 100644
--- a/compiler/GHC/Tc/Gen/Export.hs
+++ b/compiler/GHC/Tc/Gen/Export.hs
@@ -611,9 +611,9 @@ checkPatSynParent parent NoParent gname
     selErr = exportErrCtxt "pattern synonym record selector"
 
     handle_pat_syn :: SDoc
-                   -> TyCon      -- ^ Parent TyCon
-                   -> PatSyn     -- ^ Corresponding bundled PatSyn
-                                 --   and pretty printed origin
+                   -> TyCon      -- Parent TyCon
+                   -> PatSyn     -- Corresponding bundled PatSyn
+                                 -- and pretty printed origin
                    -> TcM ()
     handle_pat_syn doc ty_con pat_syn
 
diff --git a/compiler/GHC/Tc/Gen/Splice.hs b/compiler/GHC/Tc/Gen/Splice.hs
index 6860eba567..1f2c9b66eb 100644
--- a/compiler/GHC/Tc/Gen/Splice.hs
+++ b/compiler/GHC/Tc/Gen/Splice.hs
@@ -1404,7 +1404,7 @@ lookupThInstName th_type = do
         <+> ppr_th th_type
         <+> text "to add documentation to"
 
-    -- | Get the name of the class for the instance we are documenting
+    -- Get the name of the class for the instance we are documenting
     -- > inst_cls_name (Monad Maybe) == Monad
     -- > inst_cls_name C = C
     inst_cls_name :: TH.Type -> TcM TH.Name
@@ -1443,7 +1443,7 @@ lookupThInstName th_type = do
         <+> ppr_th th_type
         <+> text "is supposed to be"
 
-    -- | Basically does the opposite of 'mkThAppTs'
+    -- Basically does the opposite of 'mkThAppTs'
     -- > inst_arg_types (Monad Maybe) == [Maybe]
     -- > inst_arg_types C == []
     inst_arg_types :: TH.Type -> [TH.Type]
diff --git a/compiler/GHC/Tc/Module.hs b/compiler/GHC/Tc/Module.hs
index d8ec1e1b16..d9bb0dba17 100644
--- a/compiler/GHC/Tc/Module.hs
+++ b/compiler/GHC/Tc/Module.hs
@@ -1284,7 +1284,7 @@ checkBootTyCon is_boot tc1 tc2
     --
     -- See also 'HowAbstract' and Note [Skolem abstract data].
 
-    -- | Given @type T tvs = ty@, where @ty@ decomposes into @tc2' args@,
+    -- Given @type T tvs = ty@, where @ty@ decomposes into @tc2' args@,
     -- check that this synonym is an acceptable implementation of @tc1@.
     -- See Note [Synonyms implement abstract data]
     checkSynAbsData :: [TyVar] -> Type -> TyCon -> [Type] -> Maybe SDoc
@@ -1715,9 +1715,9 @@ tcMissingParentClassWarn warnFlag isName shouldName
        }}
   where
     -- Check whether the desired superclass exists in a given environment.
-    checkShouldInst :: Class   -- ^ Class of existing instance
-                    -> Class   -- ^ Class there should be an instance of
-                    -> ClsInst -- ^ Existing instance
+    checkShouldInst :: Class   -- Class of existing instance
+                    -> Class   -- Class there should be an instance of
+                    -> ClsInst -- Existing instance
                     -> TcM ()
     checkShouldInst isClass shouldClass isInst
       = do { instEnv <- tcGetInstEnvs
diff --git a/compiler/GHC/Tc/TyCl/Utils.hs b/compiler/GHC/Tc/TyCl/Utils.hs
index 7abde66296..e102507d63 100644
--- a/compiler/GHC/Tc/TyCl/Utils.hs
+++ b/compiler/GHC/Tc/TyCl/Utils.hs
@@ -971,14 +971,14 @@ mkOneRecordSelector all_cons idDetails fl has_sel
     eq_subst = mkTvSubstPrs (map eqSpecPair eq_spec)
     -- inst_tys corresponds to one of the following:
     --
-    -- * The arguments to the user-written return type (for GADT constructors).
-    --   In this scenario, eq_subst provides a mapping from the universally
-    --   quantified type variables to the argument types. Note that eq_subst
-    --   does not need to be applied to any other part of the DataCon
-    --   (see Note [The dcEqSpec domain invariant] in GHC.Core.DataCon).
-    -- * The universally quantified type variables
-    --   (for Haskell98-style constructors and pattern synonyms). In these
-    --   scenarios, eq_subst is an empty substitution.
+    --  * The arguments to the user-written return type (for GADT constructors).
+    --    In this scenario, eq_subst provides a mapping from the universally
+    --    quantified type variables to the argument types. Note that eq_subst
+    --    does not need to be applied to any other part of the DataCon
+    --    (see Note [The dcEqSpec domain invariant] in GHC.Core.DataCon).
+    --  * The universally quantified type variables
+    --    (for Haskell98-style constructors and pattern synonyms). In these
+    --    scenarios, eq_subst is an empty substitution.
     inst_tys = substTyVars eq_subst univ_tvs
 
     unit_rhs = mkLHsTupleExpr [] noExtField
diff --git a/compiler/GHC/Types/Demand.hs b/compiler/GHC/Types/Demand.hs
index 4163e9a525..c5a763a93a 100644
--- a/compiler/GHC/Types/Demand.hs
+++ b/compiler/GHC/Types/Demand.hs
@@ -979,7 +979,7 @@ strictifyDictDmd ty (n :* Prod b ds)
   = C_1N :* mkProd b (zipWith strictifyDictDmd field_tys ds)
       -- main idea: ensure it's strict
   where
-    -- | Return a TyCon and a list of field types if the given
+    -- Return a TyCon and a list of field types if the given
     -- type is a non-newtype dictionary type
     as_non_newtype_dict ty
       | Just (tycon, _arg_tys, _data_con, map scaledThing -> inst_con_arg_tys)
diff --git a/compiler/GHC/Unit/Module/Deps.hs b/compiler/GHC/Unit/Module/Deps.hs
index c654940730..5a50f42b35 100644
--- a/compiler/GHC/Unit/Module/Deps.hs
+++ b/compiler/GHC/Unit/Module/Deps.hs
@@ -270,7 +270,7 @@ data Usage
             -- if we directly imported it (and hence we depend on its export list)
         usg_safe :: IsSafeImport
             -- ^ Was this module imported as a safe import
-    }                                           -- ^ Module from the current package
+    }
   -- | A file upon which the module depends, e.g. a CPP #include, or using TH's
   -- 'addDependentFile'
   | UsageFile {
diff --git a/compiler/Language/Haskell/Syntax/Decls.hs b/compiler/Language/Haskell/Syntax/Decls.hs
index 64e9a0cc4e..baeef95b17 100644
--- a/compiler/Language/Haskell/Syntax/Decls.hs
+++ b/compiler/Language/Haskell/Syntax/Decls.hs
@@ -436,6 +436,13 @@ data TyClDecl pass
              , tcdFixity   :: LexicalFixity        -- ^ Fixity used in the declaration
              , tcdDataDefn :: HsDataDefn pass }
 
+    -- | - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnClass',
+    --           'GHC.Parser.Annotation.AnnWhere','GHC.Parser.Annotation.AnnOpen',
+    --           'GHC.Parser.Annotation.AnnClose'
+    --   - The tcdFDs will have 'GHC.Parser.Annotation.AnnVbar',
+    --                          'GHC.Parser.Annotation.AnnComma'
+    --                          'GHC.Parser.Annotation.AnnRarrow'
+    -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
   | ClassDecl { tcdCExt    :: XClassDecl pass,         -- ^ Post renamer, FVs
                 tcdCtxt    :: Maybe (LHsContext pass), -- ^ Context...
                 tcdLName   :: LIdP pass,               -- ^ Name of the class
@@ -448,14 +455,6 @@ data TyClDecl pass
                 tcdATDefs  :: [LTyFamDefltDecl pass],   -- ^ Associated type defaults
                 tcdDocs    :: [LDocDecl pass]           -- ^ Haddock docs
     }
-        -- ^ - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnClass',
-        --           'GHC.Parser.Annotation.AnnWhere','GHC.Parser.Annotation.AnnOpen',
-        --           'GHC.Parser.Annotation.AnnClose'
-        --   - The tcdFDs will have 'GHC.Parser.Annotation.AnnVbar',
-        --                          'GHC.Parser.Annotation.AnnComma'
-        --                          'GHC.Parser.Annotation.AnnRarrow'
-
-        -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
   | XTyClDecl !(XXTyClDecl pass)
 
 data FunDep pass
@@ -1368,6 +1367,10 @@ data FamEqn pass rhs
 type LClsInstDecl pass = XRec pass (ClsInstDecl pass)
 
 -- | Class Instance Declaration
+--  - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnInstance',
+--           'GHC.Parser.Annotation.AnnWhere',
+--           'GHC.Parser.Annotation.AnnOpen','GHC.Parser.Annotation.AnnClose',
+-- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
 data ClsInstDecl pass
   = ClsInstDecl
       { cid_ext     :: XCClsInstDecl pass
@@ -1384,12 +1387,6 @@ data ClsInstDecl pass
 
         -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
       }
-    -- ^
-    --  - 'GHC.Parser.Annotation.AnnKeywordId' : 'GHC.Parser.Annotation.AnnInstance',
-    --           'GHC.Parser.Annotation.AnnWhere',
-    --           'GHC.Parser.Annotation.AnnOpen','GHC.Parser.Annotation.AnnClose',
-
-    -- For details on above see Note [exact print annotations] in GHC.Parser.Annotation
   | XClsInstDecl !(XXClsInstDecl pass)
 
 ----------------- Instances of all kinds -------------
diff --git a/compiler/Language/Haskell/Syntax/Expr.hs b/compiler/Language/Haskell/Syntax/Expr.hs
index 555450abbb..3a309908f9 100644
--- a/compiler/Language/Haskell/Syntax/Expr.hs
+++ b/compiler/Language/Haskell/Syntax/Expr.hs
@@ -1645,13 +1645,14 @@ data ArithSeqInfo id
 -- Context of a pattern match. This is more subtle than it would seem. See Note
 -- [Varieties of pattern matches].
 data HsMatchContext p
-  = FunRhs { mc_fun        :: LIdP p    -- ^ function binder of @f@
-           , mc_fixity     :: LexicalFixity -- ^ fixing of @f@
-           , mc_strictness :: SrcStrictness -- ^ was @f@ banged?
-                                            -- See Note [FunBind vs PatBind]
-           }
-                                -- ^A pattern matching on an argument of a
-                                -- function binding
+  = FunRhs
+    -- ^ A pattern matching on an argument of a
+    -- function binding
+      { mc_fun        :: LIdP p    -- ^ function binder of @f@
+      , mc_fixity     :: LexicalFixity -- ^ fixing of @f@
+      , mc_strictness :: SrcStrictness -- ^ was @f@ banged?
+                                       -- See Note [FunBind vs PatBind]
+      }
   | LambdaExpr                  -- ^Patterns of a lambda
   | CaseAlt                     -- ^Patterns and guards on a case alternative
   | IfAlt                       -- ^Guards of a multi-way if alternative