[commit: ghc] ghc-8.0: Expand and clarify the docs for ApplicativeDo (#11835) (ba41416)

[git at git.haskell.org]

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

On branch  : ghc-8.0
Link       : http://ghc.haskell.org/trac/ghc/changeset/ba414165bbf06e3b3c4f6e65301749d197beb69a/ghc

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

commit ba414165bbf06e3b3c4f6e65301749d197beb69a
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Mon Jun 20 15:30:34 2016 +0100

    Expand and clarify the docs for ApplicativeDo (#11835)
    
    (cherry picked from commit ee3bde7999877f108375651869f1dc5b362da9fe)


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

ba414165bbf06e3b3c4f6e65301749d197beb69a
 docs/users_guide/glasgow_exts.rst | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index fd4f947..555bfb6 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -939,9 +939,21 @@ then the expression will only require ``Applicative``. Otherwise, the expression
 will require ``Monad``. The block may return a pure expression ``E`` depending
 upon the results ``p1...pn`` with either ``return`` or ``pure``.
 
-Note: the final statement really must be of the form ``return E`` or
-``pure E``, otherwise you get a ``Monad`` constraint.  Using ``$`` as
-in ``return $ E`` or ``pure $ E`` is also acceptable.
+Note: the final statement must match one of these patterns exactly:
+
+- ``return E``
+- ``return $ E``
+- ``pure E``
+- ``pure $ E``
+
+otherwise GHC cannot recognise it as a ``return`` statement, and the
+transformation to use ``<$>`` that we saw above does not apply.  In
+particular, slight variations such as ``return . Just $ x`` or ``let x
+= e in return x`` would not be recognised.
+
+If the final statement is not of one of these forms, GHC falls back to
+standard ``do`` desugaring, and the expression will require a
+``Monad`` constraint.
 
 When the statements of a ``do`` expression have dependencies between
 them, and ``ApplicativeDo`` cannot infer an ``Applicative`` type, it