Expand and clarify the docs for ApplicativeDo (#11835)
authorSimon Marlow <marlowsd@gmail.com>
Mon, 20 Jun 2016 14:30:34 +0000 (15:30 +0100)
committerSimon Marlow <marlowsd@gmail.com>
Tue, 21 Jun 2016 10:19:02 +0000 (11:19 +0100)
docs/users_guide/glasgow_exts.rst

index d5e5f7c..82b7d7c 100644 (file)
@@ -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