Split off -Wunused-type-variables from -Wunused-matches

Summary:
Previously, `-Wunused-matches` would fire whenever it detected unused type
variables in a type family or data family instance. This can be annoying for
users who wish to use type variable names as documentation, as being
`-Wall`-compliant would mean that they'd have to prefix many of their type
variable names with underscores, making the documentation harder to read.

To avoid this, a new warning `-Wunused-type-variables` was created that only
encompasses unused variables in family instances. `-Wunused-matches` reverts
back to its role of only warning on unused term-level pattern names. Unlike
`-Wunused-matches`, `-Wunused-type-variables` is not implied by `-Wall`.

Fixes #11451.

Test Plan: ./validate

Reviewers: goldfire, ekmett, austin, hvr, simonpj, bgamari

Reviewed By: simonpj, bgamari

Subscribers: thomie

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

GHC Trac Issues: #11451

1 files changed, 43 insertions, 3 deletions

diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index e4f8d2c3a7..afcee5b5d7 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -44,6 +44,7 @@ The following flags are simple ways to select standard "packages" of warnings:
 
         * :ghc-flag:`-Wunused-binds`
         * :ghc-flag:`-Wunused-matches`
+        * :ghc-flag:`-Wunused-foralls`
         * :ghc-flag:`-Wunused-imports`
         * :ghc-flag:`-Wincomplete-patterns`
         * :ghc-flag:`-Wdodgy-exports`
@@ -871,14 +872,18 @@ of ``-W(no-)*``.
        single: unused matches, warning
        single: matches, unused
 
-    Report all unused variables which arise from pattern matches,
-    including patterns consisting of a single variable. This includes
-    unused type variables in type family instances. For instance
+    Report all unused variables which arise from term-level pattern matches,
+    including patterns consisting of a single variable. For instance
     ``f x y = []`` would report ``x`` and ``y`` as unused. The warning
     is suppressed if the variable name begins with an underscore, thus: ::
 
         f _x = True
 
+    Note that :ghc-flag:`-Wunused-matches` does not warn about variables which
+    arise from type-level patterns, as found in type family and data family
+    instances. This must be enabled separately through the
+    :ghc-flag:`-Wunused-type-patterns` flag.
+
 .. ghc-flag:: -Wunused-do-bind
 
     .. index::
@@ -900,6 +905,41 @@ of ``-W(no-)*``.
 
         do { mapM_ popInt xs ; return 10 }
 
+.. ghc-flag:: -Wunused-type-patterns
+
+    .. index::
+       single: unused type patterns, warning
+       single: type patterns, unused
+
+    Report all unused type variables which arise from patterns in type family
+    and data family instances. For instance: ::
+
+        type instance F x y = []
+
+    would report ``x`` and ``y`` as unused. The warning is suppressed if the
+    type variable name begins with an underscore, like so: ::
+
+        type instance F _x _y = []
+
+    Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-variables` is
+    not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
+    unlike term-level pattern names, type names are often chosen expressly for
+    documentation purposes, so using underscores in type names can make the
+    documentation harder to read.
+
+.. ghc-flag:: -Wunused-foralls
+
+    .. index::
+       single: unused foralls, warning
+       single: foralls, unused
+
+    Report all unused type variables which arise from explicit, user-written
+    ``forall`` statements. For instance: ::
+
+        g :: forall a b c. (b -> b)
+
+    would report ``a`` and ``c`` as unused.
+
 .. ghc-flag:: -Wwrong-do-bind
 
     .. index::