Allow WARNING pragmas to be controlled with custom categories

Closes #17209. This implements GHC Proposal 541, allowing a WARNING
pragma to be annotated with a category like so:

    {-# WARNING in "x-partial" head "This function is undefined on empty lists." #-}

The user can then enable, disable and set the severity of such warnings
using command-line flags `-Wx-partial`, `-Werror=x-partial` and so on.  There
is a new warning group `-Wextended-warnings` containing all these warnings.
Warnings without a category are treated as if the category was `deprecations`,
and are (still) controlled by the flags `-Wdeprecations`
and `-Wwarnings-deprecations`.

Updates Haddock submodule.

3 files changed, 80 insertions, 19 deletions

diff --git a/docs/users_guide/9.8.1-notes.rst b/docs/users_guide/9.8.1-notes.rst
index 8d8e451e9b..e0eedfe0e7 100644
--- a/docs/users_guide/9.8.1-notes.rst
+++ b/docs/users_guide/9.8.1-notes.rst
@@ -35,6 +35,12 @@ Compiler
 - Fix a bug in TH causing excessive calls to ``setNumCapabilities`` when ``-j`` is greater than ``-N``.
   See GHC ticket #23049.
 
+- ``WARNING`` pragmas may now be annotated with a category, following
+  `GHC proposal #541 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0541-warning-pragmas-with-categories.rst>`_, in which case they are controlled with new
+  ``-Wx-⟨category⟩`` flags rather than :ghc-flag:`-Wdeprecations`.
+  A new warning group :ghc-flag:`-Wextended-warnings` includes all such warnings
+  regardless of category.  See :ref:`warning-deprecated-pragma`.
+
 
 GHCi
 ~~~~
diff --git a/docs/users_guide/exts/pragmas.rst b/docs/users_guide/exts/pragmas.rst
index 0197a2fa1a..2c8c5d4759 100644
--- a/docs/users_guide/exts/pragmas.rst
+++ b/docs/users_guide/exts/pragmas.rst
@@ -98,17 +98,17 @@ other compilers.
 
 .. pragma:: WARNING
 
-    :where: declaration
+    :where: declaration or module name
 
     The ``WARNING`` pragma allows you to attach an arbitrary warning to a
-    particular function, class, or type.
+    particular function, class, type, or module.
 
 .. pragma:: DEPRECATED
 
-    :where: declaration
+    :where: declaration or module name
 
     A ``DEPRECATED`` pragma lets you specify that a particular function, class,
-    or type is deprecated.
+    type, or module is deprecated.
 
 There are two ways of using these pragmas.
 
@@ -153,8 +153,23 @@ in an export list. The latter reduces spurious complaints within a
 library in which one module gathers together and re-exports the exports
 of several others.
 
-You can suppress the warnings with the flag
-:ghc-flag:`-Wno-warnings-deprecations <-Wwarnings-deprecations>`.
+A ``WARNING`` pragma (but not a ``DEPRECATED`` pragma) may optionally specify a
+*warning category* as a string literal following the ``in`` keyword.  This affects the flag used to suppress
+the warning.  The examples above do not specify a category, so the default
+category ``deprecations`` applies, and they can be suppressed with the flag
+:ghc-flag:`-Wno-deprecations <-Wdeprecations>` (and its synonym
+:ghc-flag:`-Wno-warnings-deprecations <-Wwarnings-deprecations>`).
+
+If a category is specified, the warning can instead be suppressed with the flag
+``-Wno-x-⟨category⟩``, for example warnings from the following pragma can be
+suppressed with ``-Wno-x-partial``::
+
+    {-# WARNING in "x-partial" head "This function is partial..." #-}
+
+Alternatively, warnings from all ``WARNING`` and ``DEPRECATED`` pragmas
+regardless of category can be suppressed with
+:ghc-flag:`-Wno-extended-warnings <-Wextended-warnings>`).
+
 
 .. _minimal-pragma:
 
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 3624a63384..c7470f7d48 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -488,27 +488,47 @@ of ``-W(no-)*``.
 
     Alias for :ghc-flag:`-Wall-missed-specialisations`
 
-.. ghc-flag:: -Wwarnings-deprecations
-    :shortdesc: warn about uses of functions & types that have warnings or
-        deprecated pragmas
+.. ghc-flag:: -Wextended-warnings
+    :shortdesc: warn about uses of functions & types that have WARNING or
+        DEPRECATED pragmas, across all categories
     :type: dynamic
-    :reverse: -Wno-warnings-deprecations
+    :reverse: -Wno-extended-warnings
     :category:
 
-    :since: 6.10
+    :since: 9.8.1
 
     :default: on
 
     .. index::
        pair: deprecations; warnings
 
-    Causes a warning to be emitted when a module, function or type with
-    a ``WARNING`` or ``DEPRECATED pragma`` is used. See
+    Causes a warning to be emitted when a module, function or type with a
+    ``WARNING`` or ``DEPRECATED`` pragma is used, regardless of the category
+    which may be associated with the pragma. See
+    :ref:`warning-deprecated-pragma` for more details on the pragmas.  This
+    implies :ghc-flag:`-Wdeprecations` and all ``-Wx-⟨category⟩`` flags.
+
+.. ghc-flag:: -Wx-⟨category⟩
+    :shortdesc: warn about uses of functions & types that have WARNING pragmas
+        with the given category
+    :type: dynamic
+    :reverse: -Wno-x-⟨category⟩
+    :category:
+
+    :since: 9.8.1
+
+    :default: on
+
+    .. index::
+       pair: deprecations; warnings
+
+    Causes a warning to be emitted when a module, function or type with a
+    ``WARNING in "x-⟨category⟩"`` pragma is used. See
     :ref:`warning-deprecated-pragma` for more details on the pragmas.
 
 .. ghc-flag:: -Wdeprecations
-    :shortdesc: warn about uses of functions & types that have warnings or
-        deprecated pragmas. Alias for :ghc-flag:`-Wwarnings-deprecations`
+    :shortdesc: warn about uses of functions & types that have DEPRECATED pragmas,
+        or WARNING pragmas with the ``deprecated`` category.
     :type: dynamic
     :reverse: -Wno-deprecations
     :category:
@@ -516,12 +536,32 @@ of ``-W(no-)*``.
     :default: on
 
     .. index::
-       single: deprecations
+       pair: deprecations; warnings
 
     Causes a warning to be emitted when a module, function or type with
-    a ``WARNING`` or ``DEPRECATED pragma`` is used. See
-    :ref:`warning-deprecated-pragma` for more details on the pragmas.
-    An alias for :ghc-flag:`-Wwarnings-deprecations`.
+    ``DEPRECATED pragma``, or a ``WARNING`` pragma with the ``deprecated``
+    category, is used. See :ref:`warning-deprecated-pragma` for more details on
+    the pragmas.
+
+.. ghc-flag:: -Wwarnings-deprecations
+    :shortdesc: warn about uses of functions & types that have DEPRECATED pragmas,
+        or WARNING pragmas with the ``deprecated`` category.
+        Alias for :ghc-flag:`-Wdeprecations`.
+    :type: dynamic
+    :reverse: -Wno-warnings-deprecations
+    :category:
+
+    :since: 6.10
+
+    :default: on
+
+    .. index::
+       pair: deprecations; warnings
+
+    Causes a warning to be emitted when a module, function or type with
+    ``DEPRECATED pragma``, or a ``WARNING`` pragma with the ``deprecated``
+    category, is used. See :ref:`warning-deprecated-pragma` for more details on
+    the pragmas. An alias for :ghc-flag:`-Wdeprecations`.
 
 .. ghc-flag:: -Wnoncanonical-monad-instances
     :shortdesc: warn when ``Applicative`` or ``Monad`` instances have