[commit: ghc] master: Document -fmax-pmcheck-iterations a bit better (5adf8f3)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/5adf8f3b74a4ee11d594b9993493bed4e3521ce2/ghc

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

commit 5adf8f3b74a4ee11d594b9993493bed4e3521ce2
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Wed Apr 27 09:57:41 2016 +0200

    Document -fmax-pmcheck-iterations a bit better


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

5adf8f3b74a4ee11d594b9993493bed4e3521ce2
 docs/users_guide/8.0.1-notes.rst          |  2 +-
 docs/users_guide/using-warnings.rst       | 12 ++++++++++++
 utils/mkUserGuidePart/Options/Warnings.hs |  5 +++++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/8.0.1-notes.rst b/docs/users_guide/8.0.1-notes.rst
index 51a9602..4db68d2 100644
--- a/docs/users_guide/8.0.1-notes.rst
+++ b/docs/users_guide/8.0.1-notes.rst
@@ -352,7 +352,7 @@ Compiler
    the pattern match checker iterates. Since coverage checking is exponential
    in the general case, setting a default number of iterations prevents memory
    and performance blowups. By default, the number of iterations is set to
-   10000000 but it can be set to ``n`` with: ``-fmax-pmcheck-iterations=n``.
+   2000000 but it can be set with: ``-fmax-pmcheck-iterations=<n>``.
    If the set number of iterations is exceeded, an informative warning is
    issued.
 
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 72e7748..46b6984 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -516,6 +516,18 @@ of ``-W(no-)*``.
         h = \[] -> 2
         Just k = f y
 
+.. ghc-flag:: -fmax-pmcheck-iterations=<N>
+
+    :default: 2000000
+
+    Sets how many iterations of the pattern-match checker will perform before
+    giving up. This limit is to catch cases where pattern-match checking might
+    be excessively costly (due to the exponential complexity of coverage
+    checking in the general case). It typically shouldn't be necessary to set
+    this unless GHC informs you that it has exceeded the pattern match checker's
+    iteration limit (in which case you may want to consider refactoring your
+    pattern match, for the sake of future readers of your code.
+
 .. ghc-flag:: -Wincomplete-record-updates
 
     .. index::
diff --git a/utils/mkUserGuidePart/Options/Warnings.hs b/utils/mkUserGuidePart/Options/Warnings.hs
index 3552172..31513d9 100644
--- a/utils/mkUserGuidePart/Options/Warnings.hs
+++ b/utils/mkUserGuidePart/Options/Warnings.hs
@@ -117,6 +117,11 @@ warningsOptions =
          , flagType = DynamicFlag
          , flagReverse = "-Wno-incomplete-uni-patterns"
          }
+  , flag { flagName = "-Wmax-pmcheck-iterations=<N>"
+         , flagDescription =
+           "the iteration limit for the pattern match checker"
+         , flagType = DynamicFlag
+         }
   , flag { flagName = "-Wincomplete-record-updates"
          , flagDescription = "warn when a record update could fail"
          , flagType = DynamicFlag