[commit: ghc] master: Improve documentation for -XStrict (98cdaee)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/98cdaee73038094eea25d994f1fd0828b3c8dd0e/ghc

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

commit 98cdaee73038094eea25d994f1fd0828b3c8dd0e
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Tue Dec 15 14:19:52 2015 +0000

    Improve documentation for -XStrict
    
    In particular, highlight that we do not put bangs on nested patterns


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

98cdaee73038094eea25d994f1fd0828b3c8dd0e
 docs/users_guide/glasgow_exts.rst | 55 +++++++++++++++++++++++++--------------
 1 file changed, 36 insertions(+), 19 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 853397a..566ecda 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -12917,27 +12917,17 @@ optionally had by adding ``!`` in front of a variable.
      let !pat = ...
 
    Adding ``~`` in front of ``x`` gives the regular lazy
-   behavior. Notice that we do not put bangs on nested patterns. For
-   example ::
-
-     let (p,q) = if flob then (undefined, undefined) else (True, False)
-     in ...
-
-   will behave like ::
-
-     let !(p,q) = if flob then (undefined, undefined) else (True,False)
-     in ...
+   behavior.
+   The general rule is that we add an implicit bang on the outermost pattern,
+   unless disabled with ``~``.
 
-   which will strictly evaluate the right hand side, and bind ``p``
-   and ``q`` to the components of the pair. But the pair itself is
-   lazy (unless we also compile the ``Prelude`` with ``Strict``; see
-   :ref:`strict-modularity` below). So ``p`` and ``q`` may end up bound to
-   undefined. See also :ref:`recursive-and-polymorphic-let-bindings` below.
+-  **Pattern matching in case expressions, lambdas, do-notation, etc**
 
--  **Case expressions.**
-
-   The patterns of a case expression get an implicit bang, unless
-   disabled with ``~``. For example ::
+   The outermost pattern of all pattern matches gets an implicit bang,
+   unless disabled with ``~``.
+   This applies to case expressions, patterns in lambda, do-notation,
+   list comprehension, and so on.
+   For example ::
 
        case x of (a,b) -> rhs
 
@@ -12962,6 +12952,33 @@ optionally had by adding ``!`` in front of a variable.
    is lazy in Haskell; but with ``Strict`` the added bang makes it
    strict.
 
+   Similarly ::
+
+      \ x -> body
+      do { x <- rhs; blah }
+      [ e | x <- rhs; blah }
+
+   all get implicit bangs on the ``x`` pattern.
+
+-  ** Nested patterns **
+
+   Notice that we do *not* put bangs on nested patterns. For
+   example ::
+
+     let (p,q) = if flob then (undefined, undefined) else (True, False)
+     in ...
+
+   will behave like ::
+
+     let !(p,q) = if flob then (undefined, undefined) else (True,False)
+     in ...
+
+   which will strictly evaluate the right hand side, and bind ``p``
+   and ``q`` to the components of the pair. But the pair itself is
+   lazy (unless we also compile the ``Prelude`` with ``Strict``; see
+   :ref:`strict-modularity` below). So ``p`` and ``q`` may end up bound to
+   undefined. See also :ref:`recursive-and-polymorphic-let-bindings` below.
+
 -  **Top level bindings.**
 
    are unaffected by ``Strict``. For example: ::