[commit: ghc] master: Expand and clarify the docs for ApplicativeDo (#11835) (ee3bde7)

[git at git.haskell.org]

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

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

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

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

    Expand and clarify the docs for ApplicativeDo (#11835)


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

ee3bde7999877f108375651869f1dc5b362da9fe
 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 d5e5f7c..82b7d7c 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -858,9 +858,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