diff --git a/compiler/GHC/Driver/Flags.hs b/compiler/GHC/Driver/Flags.hs
index 71a76e262d259faf5b37c86bb77383b38987fd8b..a323ec56fe0623f7c162c6227ac168f39a139392 100644
--- a/compiler/GHC/Driver/Flags.hs
+++ b/compiler/GHC/Driver/Flags.hs
@@ -363,7 +363,7 @@ validHoleFitsImpliedGFlags
     , (Opt_ShowTypeAppVarsOfHoleFits, turnOff, Opt_ShowTypeAppOfHoleFits)
     , (Opt_UnclutterValidHoleFits, turnOff, Opt_ShowProvOfHoleFits) ]
 
--- General flags that are switched on/off when other general flags are switched
+-- | General flags that are switched on/off when other general flags are switched
 -- on
 impliedGFlags :: [(GeneralFlag, TurnOnFlag, GeneralFlag)]
 impliedGFlags = [(Opt_DeferTypeErrors, turnOn, Opt_DeferTypedHoles)
@@ -376,12 +376,12 @@ impliedGFlags = [(Opt_DeferTypeErrors, turnOn, Opt_DeferTypedHoles)
                 ,(Opt_InfoTableMap, turnOn, Opt_InfoTableMapWithFallback)
                 ] ++ validHoleFitsImpliedGFlags
 
--- General flags that are switched on/off when other general flags are switched
+-- | General flags that are switched on/off when other general flags are switched
 -- off
 impliedOffGFlags :: [(GeneralFlag, TurnOnFlag, GeneralFlag)]
 impliedOffGFlags = [(Opt_Strictness, turnOff, Opt_WorkerWrapper)]
 
--- Please keep what_glasgow_exts_does.rst up to date with this list
+-- Please keep @docs/users_guide/what_glasgow_exts_does.rst@ up to date with this list.
 glasgowExtsFlags :: [LangExt.Extension]
 glasgowExtsFlags = [
              LangExt.ConstrainedClassMethods
@@ -429,7 +429,7 @@ data DumpFlag
    -- enabled if you run -ddump-cmm-verbose-by-proc
    -- Each flag corresponds to exact stage of Cmm pipeline.
    | Opt_D_dump_cmm_verbose
-   -- same as -ddump-cmm-verbose-by-proc but writes each stage
+   -- ^ same as -ddump-cmm-verbose-by-proc but writes each stage
    -- to a separate file (if used with -ddump-to-file)
    | Opt_D_dump_cmm_cfg
    | Opt_D_dump_cmm_cbe
@@ -503,9 +503,9 @@ data DumpFlag
    | Opt_D_dump_rn_stats
    | Opt_D_dump_opt_cmm
    | Opt_D_dump_simpl_stats
-   | Opt_D_dump_cs_trace -- Constraint solver in type checker
+   | Opt_D_dump_cs_trace -- ^ Constraint solver in type checker
    | Opt_D_dump_tc_trace
-   | Opt_D_dump_ec_trace -- Pattern match exhaustiveness checker
+   | Opt_D_dump_ec_trace -- ^ Pattern match exhaustiveness checker
    | Opt_D_dump_if_trace
    | Opt_D_dump_splices
    | Opt_D_th_dec_file
@@ -594,9 +594,13 @@ data GeneralFlag
    | Opt_InfoTableMapWithFallback
    | Opt_InfoTableMapWithStack
 
-   | Opt_WarnIsError                    -- -Werror; makes warnings fatal
-   | Opt_ShowWarnGroups                 -- Show the group a warning belongs to
-   | Opt_HideSourcePaths                -- Hide module source/object paths
+   | Opt_WarnIsError
+   -- ^ @-Werror@; makes all warnings fatal.
+   -- See 'wopt_set_fatal' for making individual warnings fatal as in @-Werror=foo@.
+   | Opt_ShowWarnGroups
+   -- ^ Show the group a warning belongs to.
+   | Opt_HideSourcePaths
+   -- ^ @-fhide-source-paths@; hide module source/object paths.
 
    | Opt_PrintExplicitForalls
    | Opt_PrintExplicitKinds
@@ -644,15 +648,15 @@ data GeneralFlag
    | Opt_IgnoreAsserts
    | Opt_DoEtaReduction
    | Opt_CaseMerge
-   | Opt_CaseFolding                    -- Constant folding through case-expressions
+   | Opt_CaseFolding                    -- ^ Constant folding through case-expressions
    | Opt_UnboxStrictFields
    | Opt_UnboxSmallStrictFields
    | Opt_DictsCheap
-   | Opt_EnableRewriteRules             -- Apply rewrite rules during simplification
-   | Opt_EnableThSpliceWarnings         -- Enable warnings for TH splices
-   | Opt_RegsGraph                      -- do graph coloring register allocation
-   | Opt_RegsIterative                  -- do iterative coalescing graph coloring register allocation
-   | Opt_PedanticBottoms                -- Be picky about how we treat bottom
+   | Opt_EnableRewriteRules             -- ^ Apply rewrite rules during simplification
+   | Opt_EnableThSpliceWarnings         -- ^ Enable warnings for TH splices
+   | Opt_RegsGraph                      -- ^ Do graph coloring register allocation
+   | Opt_RegsIterative                  -- ^ Do iterative coalescing graph coloring register allocation
+   | Opt_PedanticBottoms                -- ^ Be picky about how we treat bottom
    | Opt_LlvmFillUndefWithGarbage       -- Testing for undef bugs (hidden flag)
    | Opt_IrrefutableTuples
    | Opt_CmmSink
@@ -661,13 +665,13 @@ data GeneralFlag
    | Opt_CmmControlFlow
    | Opt_AsmShortcutting
    | Opt_OmitYields
-   | Opt_FunToThunk               -- deprecated
-   | Opt_DictsStrict                     -- be strict in argument dictionaries
+   | Opt_FunToThunk                -- deprecated
+   | Opt_DictsStrict               -- ^ Be strict in argument dictionaries
    | Opt_DmdTxDictSel              -- ^ deprecated, no effect and behaviour is now default.
                                    -- Allowed switching of a special demand transformer for dictionary selectors
-   | Opt_Loopification                  -- See Note [Self-recursive tail calls]
-   | Opt_CfgBlocklayout             -- ^ Use the cfg based block layout algorithm.
-   | Opt_WeightlessBlocklayout         -- ^ Layout based on last instruction per block.
+   | Opt_Loopification             -- See Note [Self-recursive tail calls]
+   | Opt_CfgBlocklayout            -- ^ Use the cfg based block layout algorithm.
+   | Opt_WeightlessBlocklayout     -- ^ Layout based on last instruction per block.
    | Opt_CprAnal
    | Opt_WorkerWrapper
    | Opt_WorkerWrapperUnlift  -- ^ Do W/W split for unlifting even if we won't unbox anything.
@@ -684,7 +688,7 @@ data GeneralFlag
    -- Inference flags
    | Opt_DoTagInferenceChecks
 
-   -- PreInlining is on by default. The option is there just to see how
+   -- | PreInlining is on by default. The option is there just to see how
    -- bad things get if you turn it off!
    | Opt_SimplPreInlining
 
@@ -693,15 +697,15 @@ data GeneralFlag
    | Opt_OmitInterfacePragmas
    | Opt_ExposeAllUnfoldings
    | Opt_ExposeOverloadedUnfoldings
-   | Opt_KeepAutoRules -- ^Keep auto-generated rules even if they seem to have become useless
-   | Opt_WriteInterface -- forces .hi files to be written even with -fno-code
+   | Opt_KeepAutoRules -- ^ Keep auto-generated rules even if they seem to have become useless
+   | Opt_WriteInterface -- ^ Forces .hi files to be written even with -fno-code
    | Opt_WriteSelfRecompInfo
    | Opt_WriteSelfRecompFlags -- ^ Include detailed flag information for self-recompilation debugging
-   | Opt_WriteHie -- generate .hie files
+   | Opt_WriteHie -- ^ Generate .hie files
 
    -- JavaScript opts
-   | Opt_DisableJsMinifier -- ^ render JavaScript pretty-printed instead of minified (compacted)
-   | Opt_DisableJsCsources -- ^ don't link C sources (compiled to JS) with Haskell code (compiled to JS)
+   | Opt_DisableJsMinifier -- ^ Render JavaScript pretty-printed instead of minified (compacted)
+   | Opt_DisableJsCsources -- ^ Don't link C sources (compiled to JS) with Haskell code (compiled to JS)
 
    -- profiling opts
    | Opt_AutoSccsOnIndividualCafs
@@ -784,11 +788,11 @@ data GeneralFlag
    | Opt_LinkRts
 
    -- output style opts
-   | Opt_ErrorSpans -- Include full span info in error messages,
+   | Opt_ErrorSpans -- ^ Include full span info in error messages,
                     -- instead of just the start position.
    | Opt_DeferDiagnostics
    | Opt_DiagnosticsAsJSON  -- ^ Dump diagnostics as JSON
-   | Opt_DiagnosticsShowCaret -- Show snippets of offending code
+   | Opt_DiagnosticsShowCaret -- ^ Show snippets of offending code
    | Opt_PprCaseAsLet
    | Opt_PprShowTicks
    | Opt_ShowHoleConstraints
@@ -811,29 +815,29 @@ data GeneralFlag
    | Opt_ShowLoadedModules
    | Opt_HexWordLiterals -- See Note [Print Hexadecimal Literals]
 
-   -- Suppress a coercions inner structure, replacing it with '...'
+   -- | Suppress a coercions inner structure, replacing it with '...'
    | Opt_SuppressCoercions
-   -- Suppress the type of a coercion as well
+   -- | Suppress the type of a coercion as well
    | Opt_SuppressCoercionTypes
    | Opt_SuppressVarKinds
-   -- Suppress module id prefixes on variables.
+   -- | Suppress module id prefixes on variables.
    | Opt_SuppressModulePrefixes
-   -- Suppress type applications.
+   -- | Suppress type applications.
    | Opt_SuppressTypeApplications
-   -- Suppress info such as arity and unfoldings on identifiers.
+   -- | Suppress info such as arity and unfoldings on identifiers.
    | Opt_SuppressIdInfo
-   -- Suppress separate type signatures in core, but leave types on
+   -- | Suppress separate type signatures in core, but leave types on
    -- lambda bound vars
    | Opt_SuppressUnfoldings
-   -- Suppress the details of even stable unfoldings
+   -- | Suppress the details of even stable unfoldings
    | Opt_SuppressTypeSignatures
-   -- Suppress unique ids on variables.
+   -- | Suppress unique ids on variables.
    -- Except for uniques, as some simplifier phases introduce new
    -- variables that have otherwise identical names.
    | Opt_SuppressUniques
    | Opt_SuppressStgExts
    | Opt_SuppressStgReps
-   | Opt_SuppressTicks     -- Replaces Opt_PprShowTicks
+   | Opt_SuppressTicks      -- ^ Replaces Opt_PprShowTicks
    | Opt_SuppressTimestamps -- ^ Suppress timestamps in dumps
    | Opt_SuppressCoreSizes  -- ^ Suppress per binding Core size stats in dumps
 
@@ -1033,58 +1037,58 @@ data WarningFlag =
    | Opt_WarnDerivingTypeable
    | Opt_WarnDeferredTypeErrors
    | Opt_WarnDeferredOutOfScopeVariables
-   | Opt_WarnNonCanonicalMonadInstances              -- since 8.0
-   | Opt_WarnNonCanonicalMonadFailInstances          -- since 8.0, removed 8.8
-   | Opt_WarnNonCanonicalMonoidInstances             -- since 8.0
-   | Opt_WarnMissingPatternSynonymSignatures         -- since 8.0
-   | Opt_WarnUnrecognisedWarningFlags                -- since 8.0
-   | Opt_WarnSimplifiableClassConstraints            -- Since 8.2
-   | Opt_WarnCPPUndef                                -- Since 8.2
-   | Opt_WarnUnbangedStrictPatterns                  -- Since 8.2
-   | Opt_WarnMissingHomeModules                      -- Since 8.2
-   | Opt_WarnPartialFields                           -- Since 8.4
+   | Opt_WarnNonCanonicalMonadInstances              -- ^ @since 8.0
+   | Opt_WarnNonCanonicalMonadFailInstances          -- ^ @since 8.0, has no effect since 8.8
+   | Opt_WarnNonCanonicalMonoidInstances             -- ^ @since 8.0
+   | Opt_WarnMissingPatternSynonymSignatures         -- ^ @since 8.0
+   | Opt_WarnUnrecognisedWarningFlags                -- ^ @since 8.0
+   | Opt_WarnSimplifiableClassConstraints            -- ^ @since 8.2
+   | Opt_WarnCPPUndef                                -- ^ @since 8.2
+   | Opt_WarnUnbangedStrictPatterns                  -- ^ @since 8.2
+   | Opt_WarnMissingHomeModules                      -- ^ @since 8.2
+   | Opt_WarnPartialFields                           -- ^ @since 8.4
    | Opt_WarnMissingExportList
    | Opt_WarnInaccessibleCode
-   | Opt_WarnStarIsType                              -- Since 8.6
-   | Opt_WarnStarBinder                              -- Since 8.6
-   | Opt_WarnImplicitKindVars                        -- Since 8.6
+   | Opt_WarnStarIsType                              -- ^ @since 8.6
+   | Opt_WarnStarBinder                              -- ^ @since 8.6
+   | Opt_WarnImplicitKindVars                        -- ^ @since 8.6
    | Opt_WarnSpaceAfterBang
-   | Opt_WarnMissingDerivingStrategies               -- Since 8.8
-   | Opt_WarnPrepositiveQualifiedModule              -- Since 8.10
-   | Opt_WarnUnusedPackages                          -- Since 8.10
-   | Opt_WarnInferredSafeImports                     -- Since 8.10
-   | Opt_WarnMissingSafeHaskellMode                  -- Since 8.10
-   | Opt_WarnCompatUnqualifiedImports                -- Since 8.10
+   | Opt_WarnMissingDerivingStrategies               -- ^ @since 8.8
+   | Opt_WarnPrepositiveQualifiedModule              -- ^ @since 8.10
+   | Opt_WarnUnusedPackages                          -- ^ @since 8.10
+   | Opt_WarnInferredSafeImports                     -- ^ @since 8.10
+   | Opt_WarnMissingSafeHaskellMode                  -- ^ @since 8.10
+   | Opt_WarnCompatUnqualifiedImports                -- ^ @since 8.10
    | Opt_WarnDerivingDefaults
-   | Opt_WarnInvalidHaddock                          -- Since 9.0
-   | Opt_WarnOperatorWhitespaceExtConflict           -- Since 9.2
-   | Opt_WarnOperatorWhitespace                      -- Since 9.2
-   | Opt_WarnAmbiguousFields                         -- Since 9.2
-   | Opt_WarnImplicitLift                            -- Since 9.2
-   | Opt_WarnMissingKindSignatures                   -- Since 9.2
-   | Opt_WarnMissingPolyKindSignatures               -- Since 9.8
-   | Opt_WarnMissingExportedPatternSynonymSignatures -- since 9.2
-   | Opt_WarnRedundantStrictnessFlags                -- Since 9.4
-   | Opt_WarnForallIdentifier                        -- Since 9.4
-   | Opt_WarnUnicodeBidirectionalFormatCharacters    -- Since 9.0.2
-   | Opt_WarnGADTMonoLocalBinds                      -- Since 9.4
-   | Opt_WarnTypeEqualityOutOfScope                  -- Since 9.4
-   | Opt_WarnTypeEqualityRequiresOperators           -- Since 9.4
-   | Opt_WarnLoopySuperclassSolve                    -- Since 9.6, has no effect since 9.10
-   | Opt_WarnTermVariableCapture                     -- Since 9.8
-   | Opt_WarnMissingRoleAnnotations                  -- Since 9.8
-   | Opt_WarnImplicitRhsQuantification               -- Since 9.8
-   | Opt_WarnIncompleteExportWarnings                -- Since 9.8
-   | Opt_WarnIncompleteRecordSelectors               -- Since 9.10
-   | Opt_WarnBadlyStagedTypes                        -- Since 9.10
-   | Opt_WarnInconsistentFlags                       -- Since 9.8
-   | Opt_WarnDataKindsTC                             -- Since 9.10
-   | Opt_WarnDefaultedExceptionContext               -- Since 9.10
-   | Opt_WarnViewPatternSignatures                   -- Since 9.12
-   | Opt_WarnUselessSpecialisations                  -- Since 9.14
-   | Opt_WarnDeprecatedPragmas                       -- Since 9.14
+   | Opt_WarnInvalidHaddock                          -- ^ @since 9.0
+   | Opt_WarnOperatorWhitespaceExtConflict           -- ^ @since 9.2
+   | Opt_WarnOperatorWhitespace                      -- ^ @since 9.2
+   | Opt_WarnAmbiguousFields                         -- ^ @since 9.2
+   | Opt_WarnImplicitLift                            -- ^ @since 9.2
+   | Opt_WarnMissingKindSignatures                   -- ^ @since 9.2
+   | Opt_WarnMissingPolyKindSignatures               -- ^ @since 9.8
+   | Opt_WarnMissingExportedPatternSynonymSignatures -- ^ @since 9.2
+   | Opt_WarnRedundantStrictnessFlags                -- ^ @since 9.4
+   | Opt_WarnForallIdentifier                        -- ^ @since 9.4
+   | Opt_WarnUnicodeBidirectionalFormatCharacters    -- ^ @since 9.0.2
+   | Opt_WarnGADTMonoLocalBinds                      -- ^ @since 9.4
+   | Opt_WarnTypeEqualityOutOfScope                  -- ^ @since 9.4
+   | Opt_WarnTypeEqualityRequiresOperators           -- ^ @since 9.4
+   | Opt_WarnLoopySuperclassSolve                    -- ^ @since 9.6, has no effect since 9.10
+   | Opt_WarnTermVariableCapture                     -- ^ @since 9.8
+   | Opt_WarnMissingRoleAnnotations                  -- ^ @since 9.8
+   | Opt_WarnImplicitRhsQuantification               -- ^ @since 9.8
+   | Opt_WarnIncompleteExportWarnings                -- ^ @since 9.8
+   | Opt_WarnIncompleteRecordSelectors               -- ^ @since 9.10
+   | Opt_WarnBadlyStagedTypes                        -- ^ @since 9.10
+   | Opt_WarnInconsistentFlags                       -- ^ @since 9.8
+   | Opt_WarnDataKindsTC                             -- ^ @since 9.10
+   | Opt_WarnDefaultedExceptionContext               -- ^ @since 9.10
+   | Opt_WarnViewPatternSignatures                   -- ^ @since 9.12
+   | Opt_WarnUselessSpecialisations                  -- ^ @since 9.14
+   | Opt_WarnDeprecatedPragmas                       -- ^ @since 9.14
    | Opt_WarnRuleLhsEqualities
-       -- Since 9.14, scheduled to be removed in 9.18
+       -- ^ @since 9.14, scheduled to be removed in 9.18
        --
        -- See Note [Quantifying over equalities in RULES] in GHC.Tc.Gen.Sig
    deriving (Eq, Ord, Show, Enum, Bounded)
@@ -1265,7 +1269,7 @@ warningGroupIncludesExtendedWarnings W_everything        = True
 
 -- | Warning groups.
 --
--- As all warnings are in the Weverything set, it is ignored when
+-- As all warnings are in the 'W_everything' set, it is ignored when
 -- displaying to the user which group a warning is in.
 warningGroups :: [WarningGroup]
 warningGroups = [minBound..maxBound]
@@ -1280,7 +1284,7 @@ warningGroups = [minBound..maxBound]
 -- Separating this from 'warningGroups' allows for multiple
 -- hierarchies with no inherent relation to be defined.
 --
--- The special-case Weverything group is not included.
+-- The special-case 'W_everything' group is not included.
 warningHierarchies :: [[WarningGroup]]
 warningHierarchies = hierarchies ++ map (:[]) rest
   where
@@ -1353,7 +1357,7 @@ standardWarnings -- see Note [Documenting warning flags]
         Opt_WarnRuleLhsEqualities
       ]
 
--- | Things you get with -W
+-- | Things you get with @-W@.
 minusWOpts :: [WarningFlag]
 minusWOpts
     = standardWarnings ++
@@ -1369,7 +1373,7 @@ minusWOpts
         Opt_WarnUnbangedStrictPatterns
       ]
 
--- | Things you get with -Wall
+-- | Things you get with @-Wall@.
 minusWallOpts :: [WarningFlag]
 minusWallOpts
     = minusWOpts ++
@@ -1390,11 +1394,11 @@ minusWallOpts
         Opt_WarnDerivingTypeable
       ]
 
--- | Things you get with -Weverything, i.e. *all* known warnings flags
+-- | Things you get with @-Weverything@, i.e. *all* known warnings flags.
 minusWeverythingOpts :: [WarningFlag]
 minusWeverythingOpts = [ toEnum 0 .. ]
 
--- | Things you get with -Wcompat.
+-- | Things you get with @-Wcompat@.
 --
 -- This is intended to group together warnings that will be enabled by default
 -- at some point in the future, so that library authors eager to make their
@@ -1404,7 +1408,7 @@ minusWcompatOpts
     = [ Opt_WarnImplicitRhsQuantification
       ]
 
--- | Things you get with -Wunused-binds
+-- | Things you get with @-Wunused-binds@.
 unusedBindsFlags :: [WarningFlag]
 unusedBindsFlags = [ Opt_WarnUnusedTopBinds
                    , Opt_WarnUnusedLocalBinds