Improve/fix -fcatch-bottoms documentation

Old documentation suggests that -fcatch-bottoms only adds a default
alternative to bottoming case expression, but that's not true. We use a
very simplistic "is exhaustive" check and add default alternatives to
any case expression that does not cover all constructors of the type. In
case of GADTs this simple check assumes all constructors should be
covered, even the ones ruled out by the type of the scrutinee.

Update the documentation to reflect this.

(Originally noticed in #17648)

[ci skip]

1 files changed, 13 insertions, 6 deletions

diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst
index 0955af1..8304434 100644
--- a/docs/users_guide/debugging.rst
+++ b/docs/users_guide/debugging.rst
@@ -851,14 +851,21 @@ Checking for consistency
     However forcing larger alignments in general reduces performance.
 
 .. ghc-flag:: -fcatch-bottoms
-    :shortdesc: Insert ``error`` expressions after bottoming expressions; useful
-        when debugging the compiler.
+    :shortdesc: Add a default ``error`` alternative to case expressions without
+        a default alternative.
     :type: dynamic
 
-    Instructs the simplifier to emit ``error`` expressions in the continuation
-    of empty case analyses (which should bottom and consequently not return).
-    This is helpful when debugging demand analysis bugs which can sometimes
-    manifest as segmentation faults.
+    GHC generates case expressions without a default alternative in some cases:
+
+    - When the demand analysis thinks that the scrutinee does not return (i.e. a
+      bottoming expression)
+
+    - When the scrutinee is a GADT and its type rules out some constructors, and
+      others constructors are already handled by the case expression.
+
+    With this flag GHC generates a default alternative with ``error`` in these
+    cases. This is helpful when debugging demand analysis or type checker bugs
+    which can sometimes manifest as segmentation faults.
 
 .. _checking-determinism: