[commit: ghc] wip/gadtpm: Some documentation about -Wtoo-many-guards and -ffull-guard-reasoning (e812750)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/gadtpm
Link       : http://ghc.haskell.org/trac/ghc/changeset/e8127508f0c810795bfc2da632e0957b74790401/ghc

>---------------------------------------------------------------

commit e8127508f0c810795bfc2da632e0957b74790401
Author: George Karachalias <george.karachalias at gmail.com>
Date:   Sat Dec 26 18:07:19 2015 +0100

    Some documentation about -Wtoo-many-guards and -ffull-guard-reasoning


>---------------------------------------------------------------

e8127508f0c810795bfc2da632e0957b74790401
 docs/users_guide/7.12.1-notes.rst         |  9 +++++++++
 docs/users_guide/bugs.rst                 | 14 +++++++++-----
 docs/users_guide/using-warnings.rst       | 30 ++++++++++++++++++++++++++++++
 utils/mkUserGuidePart/Options/Warnings.hs | 13 +++++++++++++
 4 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/docs/users_guide/7.12.1-notes.rst b/docs/users_guide/7.12.1-notes.rst
index a1a9d0e..5891f57 100644
--- a/docs/users_guide/7.12.1-notes.rst
+++ b/docs/users_guide/7.12.1-notes.rst
@@ -231,6 +231,15 @@ Compiler
    a warning when a pattern synonym definition doesn't have a type signature.
    It is turned off by default but enabled by ``-Wall``.
 
+-  Added the ``-Wtoo-many-guards`` flag. When enabled, this will issue a
+   warning if a pattern match contains too many guards (over 20 at the
+   moment). It is enabled by default but makes a difference only if pattern
+   match checking is also enabled.
+
+-  Added the ``-ffull-guard-reasoning`` flag. When enabled, pattern match
+   checking tries its best to reason about guards, which needs exponential
+   time and memory in the general case. It is turned off by default.
+
 GHCi
 ~~~~
 
diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index b287378..cef03d4 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -381,11 +381,15 @@ Bugs in GHC
    yield points are inserted at every function entrypoint (at the expense of a
    bit of performance).
 
--  GHC can warn about non-exhaustive or overlapping patterns (see
-   :ref:`options-sanity`), and usually does so correctly. But not
-   always. It gets confused by string patterns, and by guards, and can
-   then emit bogus warnings. The entire overlap-check code needs an
-   overhaul really.
+-  GHC's updated exhaustiveness and coverage checker (see
+   :ref:`options-sanity`) is quite expressive but with a rather high
+   performance cost (in terms of both time and memory consumption), mainly
+   due to guards. Two flags have been introduced to give more control to
+   the user over guard reasoning: ``-Wtoo-many-guards``
+   and ``-ffull-guard-reasoning`` (see :ref:`options-sanity`).
+   When ``-ffull-guard-reasoning`` is on, pattern match checking for guards
+   runs in full power, which may run out of memory/substantially increase
+   compilation time.
 
 -  GHC does not allow you to have a data type with a context that
    mentions type variables that are not data type parameters. For
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 9748e47..8bb654c 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -538,6 +538,36 @@ of ``-W(no-)*``.
     This option isn't enabled by default because it can be very noisy,
     and it often doesn't indicate a bug in the program.
 
+``-Wtoo-many-guards``
+    .. index::
+       single: -Wtoo-many-guards
+       single: too many guards, warning
+
+    The option ``-Wtoo-many-guards`` warns about places where a
+    pattern match contains too many guards (over 20 at the moment).
+    It is enabled by default but has an effect only if any form of
+    exhaustivness/overlapping checking is enabled (one of
+    ``-Wincomplete-patterns``,
+    ``-Wincomplete-uni-patterns``,
+    ``-Wincomplete-record-updates``,
+    ``-Woverlapping-patterns``). The warning can be suppressed by
+    enabling either ``-Wno-too-many-guards``, which just hides the
+    warning, or ``-ffull-guard-reasoning``.
+
+``-ffull-guard-reasoning``
+    .. index::
+       single: -ffull-guard-reasoning
+       single: guard reasoning, warning
+
+    The option ``-ffull-guard-reasoning`` forces pattern match checking
+    to run in full. This gives more precise warnings concerning pattern
+    guards but in most cases increases memory consumption and
+    compilation time. Hence, it is off by default. Enabling
+    ``-ffull-guard-reasoning`` also implies ``-Wno-too-many-guards``.
+    Note that (like ``-Wtoo-many-guards``) ``-ffull-guard-reasoning``
+    makes a difference only if pattern match checking is already
+    enabled.
+
 ``-Wmissing-fields``
     .. index::
        single: -Wmissing-fields
diff --git a/utils/mkUserGuidePart/Options/Warnings.hs b/utils/mkUserGuidePart/Options/Warnings.hs
index e56e041..c775af4 100644
--- a/utils/mkUserGuidePart/Options/Warnings.hs
+++ b/utils/mkUserGuidePart/Options/Warnings.hs
@@ -222,6 +222,11 @@ warningsOptions =
          , flagType = DynamicFlag
          , flagReverse = "-Wno-tabs"
          }
+  , flag { flagName = "-Wtoo-many-guards"
+         , flagDescription = "warn when a match has too many guards"
+         , flagType = DynamicFlag
+         , flagReverse = "-Wno-too-many-guards"
+         }
   , flag { flagName = "-Wtype-defaults"
          , flagDescription = "warn when defaulting happens"
          , flagType = DynamicFlag
@@ -364,4 +369,12 @@ warningsOptions =
          , flagType = DynamicFlag
          , flagReverse = "-Wno-deriving-typeable"
          }
+  , flag { flagName = "-ffull-guard-reasoning"
+         , flagDescription =
+           "enable the full reasoning of the pattern match checker "++
+           "concerning guards, for more precise exhaustiveness/coverage "++
+           "warnings"
+         , flagType = DynamicFlag
+         , flagReverse = "-fno-full-guard-reasoning"
+         }
   ]