[commit: ghc] master: Document peculiarities of `traceM`. (57e3742)

[git at git.haskell.org]

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

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

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

commit 57e3742c20fcc55f21634b6a43fbee47bc053775
Author: Matthias Fischmann <mf at zerobuzz.net>
Date:   Fri Oct 2 15:48:08 2015 +0200

    Document peculiarities of `traceM`.
    
    Reviewers: bgamari, hvr, austin
    
    Reviewed By: bgamari, hvr, austin
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D1289


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

57e3742c20fcc55f21634b6a43fbee47bc053775
 libraries/base/Debug/Trace.hs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/libraries/base/Debug/Trace.hs b/libraries/base/Debug/Trace.hs
index 26a19d8..653dcab 100644
--- a/libraries/base/Debug/Trace.hs
+++ b/libraries/base/Debug/Trace.hs
@@ -150,8 +150,14 @@ traceShowId a = trace (show a) a
 
 {-|
 Like 'trace' but returning unit in an arbitrary 'Applicative' context. Allows
-for convenient use in do-notation. Note that the application of 'trace' is not
-an action in the 'Applicative' context, as 'traceIO' is in the 'IO' type.
+for convenient use in do-notation.
+
+Note that the application of 'traceM' is not an action in the 'Applicative'
+context, as 'traceIO' is in the 'IO' type. While the fresh bindings in the
+following example will force the 'traceM' expressions to be reduced every time
+the @do at -block is executed, @traceM "not crashed"@ would only be reduced once,
+and the message would only be printed once.  If your monad is in 'MonadIO',
+ at liftIO . traceIO@ may be a better option.
 
 > ... = do
 >   x <- ...