Document peculiarities of `traceM`.
authorMatthias Fischmann <mf@zerobuzz.net>
Fri, 2 Oct 2015 13:48:08 +0000 (15:48 +0200)
committerBen Gamari <ben@smart-cactus.org>
Fri, 2 Oct 2015 13:51:09 +0000 (15:51 +0200)
Reviewers: bgamari, hvr, austin

Reviewed By: bgamari, hvr, austin

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D1289

libraries/base/Debug/Trace.hs

index 26a19d8..653dcab 100644 (file)
@@ -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@-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',
+@liftIO . traceIO@ may be a better option.
 
 > ... = do
 >   x <- ...