Make warnings for TH splices opt-in

In #17270 we have the pattern-match checker emit incorrect warnings. The
reason for that behavior is ultimately an inconsistency in whether we
treat TH splices as written by the user (`FromSource :: Origin`) or as
generated code (`Generated`). This was first reported in #14838.

The current solution is to TH splices as `Generated` by default and only
treat them as `FromSource` when the user requests so
(-fenable-th-splice-warnings). There are multiple reasons for opt-in
rather than opt-out:

  * It's not clear that the user that compiles a splice is the author of the code
    that produces the warning. Think of the situation where she just splices in
    code from a third-party library that produces incomplete pattern matches.
    In this scenario, the user isn't even able to fix that warning.
  * Gathering information for producing the warnings (pattern-match check
    warnings in particular) is costly. There's no point in doing so if the user
    is not interested in those warnings.

Fixes #17270, but not #14838, because the proper solution needs a GHC
proposal extending the TH AST syntax.

2 files changed, 23 insertions, 1 deletions

diff --git a/docs/users_guide/8.10.1-notes.rst b/docs/users_guide/8.10.1-notes.rst
index e5ed23ca3e..4e9a9fc613 100644
--- a/docs/users_guide/8.10.1-notes.rst
+++ b/docs/users_guide/8.10.1-notes.rst
@@ -152,7 +152,7 @@ Language
   Because GHC needs to look under a type family to see that ``a`` is determined
   by the right-hand side of ``F2``\'s equation, this now needs ``-XUndecidableInstances``.
   The problem is very much akin to its need to detect some functional dependencies.
-    
+
 Compiler
 ~~~~~~~~
 
@@ -203,6 +203,9 @@ Compiler
   and much more. See the :ref:`user guide <dynflags_plugins>` for
   more details as well as an example.
 
+- Deprecated flag :ghc-flag:`-fmax-pmcheck-iterations` in favor of
+  :ghc-flag:`-fmax-pmcheck-models`, which uses a completely different mechanism.
+
 GHCi
 ~~~~
 
@@ -274,6 +277,14 @@ Template Haskell
     tStr :: String
     tStr = show MkT
 
+- TH splices by default don't generate warnings anymore. For example,
+  ``$([d| f :: Int -> void; f x = case x of {} |])`` used to generate a
+  pattern-match exhaustivity warning, which now it doesn't. The user can
+  activate warnings for TH splices with :ghc-flag:`-fenable-th-splice-warnings`.
+  The reason for opt-in is that the offending code might not have been generated
+  by code the user has control over, for example the ``singletons`` or ``lens``
+  library.
+
 ``ghc-prim`` library
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index ec015aa673..af3d48e0a3 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -13404,6 +13404,17 @@ The syntax for a declaration splice uses "``$``" not "``splice``". The type of
 the enclosed expression must be ``Q [Dec]``, not ``[Q Dec]``. Typed expression
 splices and quotations are supported.)
 
+.. ghc-flag:: -fenable-th-splice-warnings
+    :shortdesc: Generate warnings for Template Haskell splices
+    :type: dynamic
+    :reverse: -fno-enable-th-splices
+    :category: warnings
+
+    Template Haskell splices won't be checked for warnings, because the code
+    causing the warning might originate from a third-party library and possibly
+    was not written by the user. If you want to have warnings for splices
+    anyway, pass :ghc-flag:`-fenable-th-splice-warnings`.
+
 .. _th-usage:
 
 Using Template Haskell