users_guide: Convert mkUserGuidePart generation to a Sphinx extension

This removes all dependencies the users guide had on `mkUserGuidePart`.
The generation of the flag reference table and the various pieces of the
man page is now entirely contained within the Spinx extension
`flags.py`. You can see the man page generation on the orphan page
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html

The extension works by collecting all of the meta-data attached to the
`ghc-flag` directives and then formatting and displaying it at
`flag-print` directives. There is a single printing directive that can
be customized with two options, what format to display (table, list, or
block of flags) and an optional category to limit the output to
(verbosity, warnings, codegen, etc.).

New display formats can be added by creating a function
`generate_flag_xxx` (where `xxx` is a description of the format) which
takes a list of flags and a category and returns a new `xxx`. Then just
add a reference in the dispatch table `handlers`. That display can now
be run by passing `:type: xxx` to the `flag-print` directive.

`flags.py` contains two maps of settings that can be adjusted. The first
is a canonical list of flag categories, and the second sets default
categories for files.

The only functionality that Sphinx could not replace was the
`what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just
reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx
cannot do. As the flag is deprecated, I added the list as a static file
which can be updated manually.

Additionally, this patch updates every single documented flag with the
data from `mkUserGuidePart` to generate the reference table.

Fixes #11654 and, incidentally, #12155.

Reviewers: austin, bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #11654, #12155

Differential Revision: https://phabricator.haskell.org/D3839

1 files changed, 408 insertions, 24 deletions

diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 48a9296b1a..39d7de4147 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -37,6 +37,10 @@ generally likely to indicate bugs in your program. These are:
 The following flags are simple ways to select standard "packages" of warnings:
 
 .. ghc-flag:: -W
+    :shortdesc: enable normal warnings
+    :type: dynamic
+    :reverse: -w
+    :category:
 
     Provides the standard warnings plus
 
@@ -53,6 +57,10 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wunbanged-strict-patterns`
 
 .. ghc-flag:: -Wall
+    :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
+    :type: dynamic
+    :reverse: -w
+    :category:
 
     Turns on all warning options that indicate potentially suspicious
     code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
@@ -72,6 +80,11 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wredundant-constraints`
 
 .. ghc-flag:: -Wcompat
+    :shortdesc: enable future compatibility warnings
+        (details in :ref:`options-sanity`)
+    :type: dynamic
+    :reverse: -Wno-compat
+    :category:
 
     Turns on warnings that will be enabled by default in the future, but remain
     off in normal compilations for the time being. This allows library authors
@@ -88,10 +101,17 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wnoncanonical-monoid-instances`
 
 .. ghc-flag:: -Wno-compat
+    :shortdesc: Disables all warnings enabled by :ghc-flag:`-Wcompat`.
+    :type: dynamic
+    :reverse: -Wcompat
+    :category:
 
     Disables all warnings enabled by :ghc-flag:`-Wcompat`.
 
 .. ghc-flag:: -w
+    :shortdesc: disable all warnings
+    :type: dynamic
+    :category:
 
     Turns off all warnings, including the standard ones and those that
     :ghc-flag:`-Wall` doesn't enable.
@@ -100,11 +120,19 @@ These options control which warnings are considered fatal and cause compilation
 to abort.
 
 .. ghc-flag:: -Werror
+    :shortdesc: make warnings fatal
+    :type: dynamic
+    :reverse: -Wwarn
+    :category:
 
     Makes any warning into a fatal error. Useful so that you don't miss
     warnings when doing batch compilation.
 
 .. ghc-flag:: -Werror=⟨wflag⟩
+    :shortdesc: make a specific warning fatal
+    :type: dynamic
+    :reverse: -Wwarn=⟨wflag⟩
+    :category:
     :noindex:
 
     :implies: ``-W<wflag>``
@@ -113,11 +141,19 @@ to abort.
     it hasn't been enabled yet.
 
 .. ghc-flag:: -Wwarn
+    :shortdesc: make warnings non-fatal
+    :type: dynamic
+    :reverse: -Werror
+    :category:
 
     Warnings are treated only as warnings, not as errors. This is the
     default, but can be useful to negate a :ghc-flag:`-Werror` flag.
 
 .. ghc-flag:: -Wwarn=⟨wflag⟩
+    :shortdesc: make a specific warning non-fatal
+    :type: dynamic
+    :reverse: -Werror=⟨wflag⟩
+    :category:
     :noindex:
 
     Causes a specific warning to be treated as normal warning, not fatal error.
@@ -129,6 +165,10 @@ When a warning is emitted, the specific warning flag which controls
 it is shown.
 
 .. ghc-flag:: -fshow-warning-groups
+    :shortdesc: show which group an emitted warning belongs to.
+    :type: dynamic
+    :reverse: -fno-show-warning-groups
+    :category:
 
     When showing which flag controls a warning, also show the
     respective warning group flag(s) that warning is contained in.
@@ -142,6 +182,11 @@ all these warnings can still be controlled with ``-f(no-)warn-*`` instead
 of ``-W(no-)*``.
 
 .. ghc-flag:: -Wunrecognised-warning-flags
+    :shortdesc: throw a warning when an unreconised ``-W...`` flag is
+        encountered on the command line.
+    :type: dynamic
+    :reverse: -Wno-unrecognised-warning-flags
+    :category:
 
     Enables warnings when the compiler encounters a ``-W...`` flag that is not
     recognised.
@@ -149,6 +194,12 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -Wtyped-holes
+    :shortdesc: Report warnings when :ref:`typed hole <typed-holes>` errors are
+        :ref:`deferred until runtime <defer-type-errors>`. See
+        :ghc-flag:`-fdefer-typed-holes`.
+    :type: dynamic
+    :reverse: -Wno-typed-holes
+    :category:
 
     Determines whether the compiler reports typed holes warnings. Has no
     effect unless typed holes errors are deferred until runtime. See
@@ -156,7 +207,13 @@ of ``-W(no-)*``.
 
     This warning is on by default.
 
-.. ghc-flag:: -Wtype-errors
+.. ghc-flag:: -Wdeferred-type-errors
+    :shortdesc: Report warnings when :ref:`deferred type errors
+        <defer-type-errors>` are enabled. This option is enabled by
+        default. See :ghc-flag:`-fdefer-type-errors`.
+    :type: dynamic
+    :reverse: -Wno-deferred-type-errors
+    :category:
 
     Causes a warning to be reported when a type error is deferred until
     runtime. See :ref:`defer-type-errors`
@@ -164,6 +221,14 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -fdefer-type-errors
+    :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
+        runtime <defer-type-errors>`. Implies
+        :ghc-flag:`-fdefer-typed-holes` and
+        :ghc-flag:`-fdefer-out-of-scope-variables`.
+        See also :ghc-flag:`-Wdeferred-type-errors`
+    :type: dynamic
+    :reverse: -fno-defer-type-errors
+    :category:
 
     :implies: :ghc-flag:`-fdefer-typed-holes`
 
@@ -174,6 +239,13 @@ of ``-W(no-)*``.
     :ref:`defer-type-errors`
 
 .. ghc-flag:: -fdefer-typed-holes
+    :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
+        :ref:`deferring the error until runtime <defer-type-errors>`.
+        Implied by :ghc-flag:`-fdefer-type-errors`.
+        See also :ghc-flag:`-Wtyped-holes`.
+    :type: dynamic
+    :reverse: -fno-defer-typed-holes
+    :category:
 
     Defer typed holes errors (errors about names with a leading underscore
     (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
@@ -185,6 +257,12 @@ of ``-W(no-)*``.
     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
 
 .. ghc-flag:: -fdefer-out-of-scope-variables
+    :shortdesc: Convert variable out of scope variables errors into warnings.
+        Implied by :ghc-flag:`-fdefer-type-errors`.
+        See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
+    :type: dynamic
+    :reverse: -fno-defer-out-of-scope-variables
+    :category:
 
     Defer variable out-of-scope errors (errors about names without a leading underscore)
     until runtime. This will turn variable-out-of-scope errors into warnings.
@@ -195,10 +273,24 @@ of ``-W(no-)*``.
     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
 
 .. ghc-flag:: -Wdeferred-out-of-scope-variables
+    :shortdesc: Report warnings when variable out-of-scope errors are
+        :ref:`deferred until runtime.
+        See :ghc-flag:`-fdefer-out-of-scope-variables`.
+    :type: dynamic
+    :reverse: -Wno-deferred-out-of-scope-variables
+    :category:
 
     Warn when a deferred out-of-scope variable is encountered.
 
 .. ghc-flag:: -Wpartial-type-signatures
+    :shortdesc: warn about holes in partial type signatures when
+        :ghc-flag:`-XPartialTypeSignatures` is enabled. Not applicable when
+        :ghc-flag:`-XPartialTypesignatures` is not enabled, in which case
+        errors are generated for such holes. See
+        :ref:`partial-type-signatures`.
+    :type: dynamic
+    :reverse: -Wno-partial-type-signatures
+    :category:
 
     Determines whether the compiler reports holes in partial type
     signatures as warnings. Has no effect unless
@@ -209,6 +301,10 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -fhelpful-errors
+    :shortdesc: Make suggestions for mis-spelled names.
+    :type: dynamic
+    :reverse: -fno-helpful-errors
+    :category:
 
     When a name or package is not found in scope, make suggestions for
     the name or package you might have meant instead.
@@ -216,6 +312,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wunrecognised-pragmas
+    :shortdesc: warn about uses of pragmas that GHC doesn't recognise
+    :type: dynamic
+    :reverse: -Wno-unrecognised-pragmas
+    :category:
 
     Causes a warning to be emitted when a pragma that GHC doesn't
     recognise is used. As well as pragmas that GHC itself uses, GHC also
@@ -225,22 +325,47 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wmissed-specialisations
-              -Wall-missed-specialisations
+    :shortdesc: warn when specialisation of an imported, overloaded function
+        fails.
+    :type: dynamic
+    :reverse: -Wno-missed-specialisations
+    :category:
 
     Emits a warning if GHC cannot specialise an overloaded function, usually
-    because the function needs an ``INLINABLE`` pragma. The "all" form reports
-    all such situations whereas the "non-all" form only reports when the
+    because the function needs an ``INLINABLE`` pragma. Reports when the
     situation arises during specialisation of an imported function.
 
-    The "non-all" form is intended to catch cases where an imported function
-    that is marked as ``INLINABLE`` (presumably to enable specialisation) cannot
-    be specialised as it calls other functions that are themselves not specialised.
+    This form is intended to catch cases where an imported function
+    that is marked as ``INLINABLE`` (presumably to enable specialisation)
+    cannot be specialised as it calls other functions that are themselves not
+    specialised.
 
-    Note that these warnings will not throw errors if used with :ghc-flag:`-Werror`.
+    Note that this warning will not throw errors if used with
+    :ghc-flag:`-Werror`.
 
-    These options are both off by default.
+    This option is off by default.
+
+.. ghc-flag:: -Wall-missed-specialisations
+    :shortdesc: warn when specialisation of any overloaded function fails.
+    :type: dynamic
+    :reverse: -Wno-all-missed-specialisations
+    :category:
+
+    Emits a warning if GHC cannot specialise an overloaded function, usually
+    because the function needs an ``INLINABLE`` pragma. Reports
+    all such situations.
+
+    Note that this warning will not throw errors if used with
+    :ghc-flag:`-Werror`.
+
+    This option is off by default.
 
 .. ghc-flag:: -Wwarnings-deprecations
+    :shortdesc: warn about uses of functions & types that have warnings or
+        deprecated pragmas
+    :type: dynamic
+    :reverse: -Wno-warnings-deprecations
+    :category:
 
     .. index::
        pair: deprecations; warnings
@@ -252,6 +377,11 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wdeprecations
+    :shortdesc: warn about uses of functions & types that have warnings or
+        deprecated pragmas. Alias for :ghc-flag:`-Wwarnings-deprecations`
+    :type: dynamic
+    :reverse: -Wno-deprecations
+    :category:
 
     .. index::
        single: deprecations
@@ -264,6 +394,11 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wamp
+    :shortdesc: *(deprecated)* warn on definitions conflicting with the
+        Applicative-Monad Proposal (AMP)
+    :type: dynamic
+    :reverse: -Wno-amp
+    :category:
 
     .. index::
        single: AMP
@@ -275,6 +410,13 @@ of ``-W(no-)*``.
     the AMP (Applicative-Monad proosal).
 
 .. ghc-flag:: -Wnoncanonical-monad-instances
+    :shortdesc: warn when ``Applicative`` or ``Monad`` instances have
+        noncanonical definitions of ``return``, ``pure``, ``(>>)``,
+        or ``(*>)``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monad-instances
+    :category:
 
     Warn if noncanonical ``Applicative`` or ``Monad`` instances
     declarations are detected.
@@ -295,6 +437,12 @@ of ``-W(no-)*``.
     This option is off by default.
 
 .. ghc-flag:: -Wnoncanonical-monadfail-instances
+    :shortdesc: warn when ``Monad`` or ``MonadFail`` instances have
+        noncanonical definitions of ``fail``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monadfail-instances
+    :category:
 
     Warn if noncanonical ``Monad`` or ``MonadFail`` instances
     declarations are detected.
@@ -317,6 +465,12 @@ of ``-W(no-)*``.
     This option is off by default.
 
 .. ghc-flag:: -Wnoncanonical-monoid-instances
+    :shortdesc: warn when ``Semigroup`` or ``Monoid`` instances have
+        noncanonical definitions of ``(<>)`` or ``mappend``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monoid-instances
+    :category:
 
     Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
     declarations are detected.
@@ -337,6 +491,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wcompat` option group.
 
 .. ghc-flag:: -Wmissing-monadfail-instances
+    :shortdesc: Warn when a failable pattern is used in a do-block that does
+        not have a ``MonadFail`` instance.
+    :type: dynamic
+    :reverse: -Wno-missing-monadfail-instances
+    :category:
 
     .. index::
        single: MFP
@@ -353,6 +512,11 @@ of ``-W(no-)*``.
     <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
 
 .. ghc-flag:: -Wsemigroup
+    :shortdesc: warn when a ``Monoid`` is not ``Semigroup``, and on non-
+        ``Semigroup`` definitions of ``(<>)``?
+    :type: dynamic
+    :reverse: -Wno-semigroup
+    :category:
 
     .. index::
        single: semigroup; warning
@@ -368,6 +532,10 @@ of ``-W(no-)*``.
     default, but will be switched on in a future GHC release.
 
 .. ghc-flag:: -Wdeprecated-flags
+    :shortdesc: warn about uses of commandline flags that are deprecated
+    :type: dynamic
+    :reverse: -Wno-deprecated-flags
+    :category:
 
     .. index::
        single: deprecated flags
@@ -378,6 +546,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wunsupported-calling-conventions
+    :shortdesc: warn about use of an unsupported calling convention
+    :type: dynamic
+    :reverse: -Wno-unsupported-calling-conventions
+    :category:
 
     Causes a warning to be emitted for foreign declarations that use
     unsupported calling conventions. In particular, if the ``stdcall``
@@ -385,6 +557,10 @@ of ``-W(no-)*``.
     it will be treated as ``ccall``.
 
 .. ghc-flag:: -Wdodgy-foreign-imports
+    :shortdesc: warn about dodgy foreign imports
+    :type: dynamic
+    :reverse: -Wno-dodgy-foreign-import
+    :category:
 
     Causes a warning to be emitted for foreign imports of the following
     form: ::
@@ -403,6 +579,10 @@ of ``-W(no-)*``.
     warning.
 
 .. ghc-flag:: -Wdodgy-exports
+    :shortdesc: warn about dodgy exports
+    :type: dynamic
+    :reverse: -Wno-dodgy-exports
+    :category:
 
     Causes a warning to be emitted when a datatype ``T`` is exported
     with all constructors, i.e. ``T(..)``, but is it just a type
@@ -412,6 +592,10 @@ of ``-W(no-)*``.
     but that module exports nothing.
 
 .. ghc-flag:: -Wdodgy-imports
+    :shortdesc: warn about dodgy imports
+    :type: dynamic
+    :reverse: -Wno-dodgy-imports
+    :category:
 
     Causes a warning to be emitted in the following cases:
 
@@ -422,16 +606,28 @@ of ``-W(no-)*``.
        exported.
 
 .. ghc-flag:: -Woverflowed-literals
+    :shortdesc: warn about literals that will overflow their type
+    :type: dynamic
+    :reverse: -Wno-overflowed-literals
+    :category:
 
     Causes a warning to be emitted if a literal will overflow, e.g.
     ``300 :: Word8``.
 
 .. ghc-flag:: -Wempty-enumerations
+    :shortdesc: warn about enumerations that are empty
+    :type: dynamic
+    :reverse: -Wno-empty-enumerations
+    :category:
 
     Causes a warning to be emitted if an enumeration is empty, e.g.
     ``[5 .. 3]``.
 
 .. ghc-flag:: -Wduplicate-constraints
+    :shortdesc: warn when a constraint appears duplicated in a type signature
+    :type: dynamic
+    :reverse: -Wno-duplicate-constraints
+    :category:
 
     .. index::
        single: duplicate constraints, warning
@@ -447,6 +643,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wredundant-constraints`.
 
 .. ghc-flag:: -Wredundant-constraints
+    :shortdesc: Have the compiler warn about redundant constraints in type
+        signatures.
+    :type: dynamic
+    :reverse: -Wno-redundant-constraints
+    :category:
 
     :since: 8.0
 
@@ -492,6 +693,10 @@ of ``-W(no-)*``.
     constraint is needed, so no warning is issued.
 
 .. ghc-flag:: -Wduplicate-exports
+    :shortdesc: warn when an entity is exported multiple times
+    :type: dynamic
+    :reverse: -Wno-duplicate-exports
+    :category:
 
     .. index::
        single: duplicate exports, warning
@@ -505,6 +710,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Whi-shadowing
+    :shortdesc: warn when a ``.hi`` file in the current directory shadows a library
+    :type: dynamic
+    :reverse: -Wno-hi-shadowing
+    :category:
 
     .. index::
        single: shadowing; interface files
@@ -514,6 +723,11 @@ of ``-W(no-)*``.
     name in a library or other directory.
 
 .. ghc-flag:: -Widentities
+    :shortdesc: warn about uses of Prelude numeric conversions that are probably
+        the identity (and hence could be omitted)
+    :type: dynamic
+    :reverse: -Wno-identities
+    :category:
 
     Causes the compiler to emit a warning when a Prelude numeric
     conversion converts a type ``T`` to the same type ``T``; such calls are
@@ -521,27 +735,34 @@ of ``-W(no-)*``.
     ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
 
 .. ghc-flag:: -Wimplicit-prelude
+    :shortdesc: warn when the Prelude is implicitly imported
+    :type: dynamic
+    :reverse: -Wno-implicit-prelude
+    :category:
 
     .. index::
        single: implicit prelude, warning
 
-    Have the compiler warn if the Prelude is implicitly imported. This
-    happens unless either the Prelude module is explicitly imported with
-    an ``import ... Prelude ...`` line, or this implicit import is
-    disabled (either by :ghc-flag:`-XNoImplicitPrelude` or a
-    ``LANGUAGE NoImplicitPrelude`` pragma).
+    Have the compiler warn if the Prelude is implicitly imported. This happens
+    unless either the Prelude module is explicitly imported with an ``import
+    ... Prelude ...`` line, or this implicit import is disabled (either by
+    :ghc-flag:`-XNoImplicitPrelude` or a ``LANGUAGE NoImplicitPrelude``
+    pragma).
 
-    Note that no warning is given for syntax that implicitly refers to
-    the Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
-    refers to the Prelude. For example, no warning is given when ``368``
-    means ``Prelude.fromInteger (368::Prelude.Integer)`` (where
-    ``Prelude`` refers to the actual Prelude module, regardless of the
-    imports of the module being compiled).
+    Note that no warning is given for syntax that implicitly refers to the
+    Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
+    refers to the Prelude. For example, no warning is given when ``368`` means
+    ``Prelude.fromInteger (368::Prelude.Integer)`` (where ``Prelude`` refers
+    to the actual Prelude module, regardless of the imports of the module
+    being compiled).
 
     This warning is off by default.
 
 .. ghc-flag:: -Wincomplete-patterns
-              -Wincomplete-uni-patterns
+    :shortdesc: warn when a pattern match could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-patterns
+    :category:
 
     .. index::
        single: incomplete patterns, warning
@@ -559,14 +780,26 @@ of ``-W(no-)*``.
     generally considered good practice to cover all the cases in your
     functions, and it is switched on by :ghc-flag:`-W`.
 
-    The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar, except that
-    it applies only to lambda-expressions and pattern bindings,
-    constructs that only allow a single pattern: ::
+
+.. ghc-flag:: -Wincomplete-uni-patterns
+    :shortdesc: warn when a pattern match in a lambda expression or
+        pattern binding could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-uni-patterns
+    :category:
+
+    The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
+    :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
+    lambda-expressions and pattern bindings, constructs that only allow a
+    single pattern: ::
 
         h = \[] -> 2
         Just k = f y
 
 .. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
+    :shortdesc: the iteration limit for the pattern match checker
+    :type: dynamic
+    :category:
 
     :default: 2000000
 
@@ -579,6 +812,10 @@ of ``-W(no-)*``.
     pattern match, for the sake of future readers of your code.
 
 .. ghc-flag:: -Wincomplete-record-updates
+    :shortdesc: warn when a record update could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-record-updates
+    :category:
 
     .. index::
        single: incomplete record updates, warning
@@ -598,6 +835,10 @@ of ``-W(no-)*``.
     and it often doesn't indicate a bug in the program.
 
 .. ghc-flag:: -Wmissing-fields
+    :shortdesc: warn when fields of a record are uninitialised
+    :type: dynamic
+    :reverse: -Wno-missing-fields
+    :category:
 
     .. index::
        single: missing fields, warning
@@ -610,6 +851,11 @@ of ``-W(no-)*``.
     programmer error.
 
 .. ghc-flag:: -Wmissing-import-lists
+    :shortdesc: warn when an import declaration does not explicitly list all the
+        names brought into scope
+    :type: dynamic
+    :reverse: -fnowarn-missing-import-lists
+    :category:
 
     .. index::
        single: missing import lists, warning
@@ -632,6 +878,10 @@ of ``-W(no-)*``.
     unlikely to produce ambiguity in ``M``.
 
 .. ghc-flag:: -Wmissing-methods
+    :shortdesc: warn when class methods are undefined
+    :type: dynamic
+    :reverse: -Wno-missing-methods
+    :category:
 
     .. index::
        single: missing methods, warning
@@ -658,6 +908,10 @@ of ``-W(no-)*``.
     :ref:`minimal-pragma`.
 
 .. ghc-flag:: -Wmissing-signatures
+    :shortdesc: warn about top-level functions without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -668,6 +922,12 @@ of ``-W(no-)*``.
     option is off by default.
 
 .. ghc-flag:: -Wmissing-exported-sigs
+    :shortdesc: *(deprecated)*
+        warn about top-level functions without signatures, only if they
+        are exported. takes precedence over -Wmissing-signatures
+    :type: dynamic
+    :reverse: -Wno-missing-exported-sigs
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -676,6 +936,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wmissing-exported-signatures`.
 
 .. ghc-flag:: -Wmissing-exported-signatures
+    :shortdesc: warn about top-level functions without signatures, only if they
+        are exported. takes precedence over -Wmissing-signatures
+    :type: dynamic
+    :reverse: -Wno-missing-exported-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -688,6 +953,11 @@ of ``-W(no-)*``.
     reports the inferred type. The option is off by default.
 
 .. ghc-flag:: -Wmissing-local-sigs
+    :shortdesc: *(deprecated)*
+        warn about polymorphic local bindings without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-local-sigs
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -696,6 +966,10 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wmissing-local-signatures`.
 
 .. ghc-flag:: -Wmissing-local-signatures
+    :shortdesc: warn about polymorphic local bindings without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-local-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -706,6 +980,10 @@ of ``-W(no-)*``.
     default.
 
 .. ghc-flag:: -Wmissing-pattern-synonym-signatures
+    :shortdesc: warn when pattern synonyms do not have type signatures
+    :type: dynamic
+    :reverse: -Wno-missing-pattern-synonym-signatures
+    :category:
 
     .. index::
          single: type signatures, missing, pattern synonyms
@@ -719,6 +997,10 @@ of ``-W(no-)*``.
     type. This option is off by default.
 
 .. ghc-flag:: -Wname-shadowing
+    :shortdesc: warn when names are shadowed
+    :type: dynamic
+    :reverse: -Wno-name-shadowing
+    :category:
 
     .. index::
        single: shadowing, warning
@@ -736,6 +1018,11 @@ of ``-W(no-)*``.
         f x = do { _ignore <- this; _ignore <- that; return (the other) }
 
 .. ghc-flag:: -Worphans
+    :shortdesc: warn when the module contains :ref:`orphan instance declarations
+        or rewrite rules <orphan-modules>`
+    :type: dynamic
+    :reverse: -Wno-orphans
+    :category:
 
     .. index::
        single: orphan instances, warning
@@ -758,6 +1045,10 @@ of ``-W(no-)*``.
     instances.
 
 .. ghc-flag:: -Woverlapping-patterns
+    :shortdesc: warn about overlapping patterns
+    :type: dynamic
+    :reverse: -Wno-overlapping-patterns
+    :category:
 
     .. index::
        single: overlapping patterns, warning
@@ -776,6 +1067,11 @@ of ``-W(no-)*``.
     is a programmer mistake/error, so this option is enabled by default.
 
 .. ghc-flag:: -Wsimplifiable-class-constraints
+    :shortdesc: 2arn about class constraints in a type signature that can
+        be simplified using a top-level instance declaration.
+    :type: dynamic
+    :reverse: -Wno-overlapping-patterns
+    :category:
 
     :since: 8.2
 
@@ -799,6 +1095,10 @@ of ``-W(no-)*``.
     <-Wsimplifiable-class-constraints>`.
 
 .. ghc-flag:: -Wtabs
+    :shortdesc: warn if there are tabs in the source file
+    :type: dynamic
+    :reverse: -Wno-tabs
+    :category:
 
     .. index::
        single: tabs, warning
@@ -806,6 +1106,10 @@ of ``-W(no-)*``.
     Have the compiler warn if there are tabs in your source file.
 
 .. ghc-flag:: -Wtype-defaults
+    :shortdesc: warn when defaulting happens
+    :type: dynamic
+    :reverse: -Wno-type-defaults
+    :category:
 
     .. index::
        single: defaulting mechanism, warning
@@ -822,6 +1126,10 @@ of ``-W(no-)*``.
     This warning is off by default.
 
 .. ghc-flag:: -Wmonomorphism-restriction
+    :shortdesc: warn when the Monomorphism Restriction is applied
+    :type: dynamic
+    :reverse: -Wno-monomorphism-restriction
+    :category:
 
     .. index::
        single: monomorphism restriction, warning
@@ -834,10 +1142,19 @@ of ``-W(no-)*``.
     This warning is off by default.
 
 .. ghc-flag:: -Wunsupported-llvm-version
+    :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
+        version of LLVM.
+    :type: dynamic
+    :reverse: -Wno-monomorphism-restriction
+    :category:
 
     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
 
 .. ghc-flag:: -Wunticked-promoted-constructors
+    :shortdesc: warn if promoted constructors are not ticked
+    :type: dynamic
+    :reverse: -Wno-unticked-promoted-constructors
+    :category:
 
     .. index::
        single: promoted constructor, warning
@@ -859,6 +1176,12 @@ of ``-W(no-)*``.
     This warning is enabled by default in :ghc-flag:`-Wall` mode.
 
 .. ghc-flag:: -Wunused-binds
+    :shortdesc: warn about bindings that are unused. Alias for
+        :ghc-flag:`-Wunused-top-binds`, :ghc-flag:`-Wunused-local-binds` and
+        :ghc-flag:`-Wunused-pattern-binds`
+    :type: dynamic
+    :reverse: -Wno-unused-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -872,6 +1195,10 @@ of ``-W(no-)*``.
     -  :ghc-flag:`-Wunused-pattern-binds`
 
 .. ghc-flag:: -Wunused-top-binds
+    :shortdesc: warn about top-level bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-top-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -902,6 +1229,10 @@ of ``-W(no-)*``.
         _w = True                    -- No warning: _w starts with an underscore
 
 .. ghc-flag:: -Wunused-local-binds
+    :shortdesc: warn about local bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-local-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -914,6 +1245,10 @@ of ``-W(no-)*``.
         g = h x                      -- No warning: g is unused, but is a top-level binding
 
 .. ghc-flag:: -Wunused-pattern-binds
+    :shortdesc: warn about pattern match bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-pattern-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -936,6 +1271,10 @@ of ``-W(no-)*``.
     it forces evaluation, and is useful as an alternative to ``seq``.
 
 .. ghc-flag:: -Wunused-imports
+    :shortdesc: warn about unnecessary imports
+    :type: dynamic
+    :reverse: -Wno-unused-imports
+    :category:
 
     .. index::
        single: unused imports, warning
@@ -947,6 +1286,10 @@ of ``-W(no-)*``.
     declarations, which are anonymous in Haskell.
 
 .. ghc-flag:: -Wunused-matches
+    :shortdesc: warn about variables in patterns that aren't used
+    :type: dynamic
+    :reverse: -Wno-unused-matches
+    :category:
 
     .. index::
        single: unused matches, warning
@@ -965,6 +1308,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wunused-type-patterns` flag.
 
 .. ghc-flag:: -Wunused-do-bind
+    :shortdesc: warn about do bindings that appear to throw away values of types
+        other than ``()``
+    :type: dynamic
+    :reverse: -Wno-unused-do-bind
+    :category:
 
     .. index::
        single: unused do binding, warning
@@ -986,6 +1334,11 @@ of ``-W(no-)*``.
         do { mapM_ popInt xs ; return 10 }
 
 .. ghc-flag:: -Wunused-type-patterns
+    :shortdesc: warn about unused type variables which arise from patterns
+        in type family and data family instances
+    :type: dynamic
+    :reverse: -Wno-unused-type-patterns
+    :category:
 
     .. index::
        single: unused type patterns, warning
@@ -1008,6 +1361,11 @@ of ``-W(no-)*``.
     documentation harder to read.
 
 .. ghc-flag:: -Wunused-foralls
+    :shortdesc: warn about type variables in user-written
+        ``forall``\\s that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-foralls
+    :category:
 
     .. index::
        single: unused foralls, warning
@@ -1021,6 +1379,11 @@ of ``-W(no-)*``.
     would report ``a`` and ``c`` as unused.
 
 .. ghc-flag:: -Wwrong-do-bind
+    :shortdesc: warn about do bindings that appear to throw away monadic values
+        that you should have bound instead
+    :type: dynamic
+    :reverse: -Wno-wrong-do-bind
+    :category:
 
     .. index::
        single: apparently erroneous do binding, warning
@@ -1044,12 +1407,21 @@ of ``-W(no-)*``.
         do { popInt 10 ; return 10 }
 
 .. ghc-flag:: -Winline-rule-shadowing
+    :shortdesc: Warn if a rewrite RULE might fail to fire because the
+        function might be inlined before the rule has a chance to fire.
+        See :ref:`rules-inline`.
+    :type: dynamic
+    :reverse: -Wno-inline-rule-shadowing
+    :category:
 
     Warn if a rewrite RULE might fail to fire because the function might
     be inlined before the rule has a chance to fire. See
     :ref:`rules-inline`.
 
 .. ghc-flag:: -Wcpp-undef
+    :shortdesc: warn on uses of the `#if` directive on undefined identifiers
+    :type: dynamic
+    :category:
 
     :since: 8.2
 
@@ -1058,12 +1430,24 @@ of ``-W(no-)*``.
     undefined identifiers.
 
 .. ghc-flag:: -Wunbanged-strict-patterns
+    :shortdesc: warn on pattern bind of unlifted variable that is neither bare
+        nor banged
+    :type: dynamic
+    :reverse: -Wno-unbanged-strict-patterns
+    :category:
 
     This flag warns whenever you write a pattern that binds a variable whose
     type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
     See :ref:`glasgow-unboxed` for information about unlifted types.
 
 .. ghc-flag:: -Wmissing-home-modules
+    :shortdesc: warn when encountering a home module imported, but not listed
+        on the command line. Useful for cabal to ensure GHC won't pick
+        up modules, not listed neither in ``exposed-modules``, nor in
+        ``other-modules``.
+    :type: dynamic
+    :reverse: -Wno-missing-home-modules
+    :category:
 
     :since: 8.2