[commit: ghc] ghc-7.10: Improve documentation of 'trace' (d67b784)

[git at git.haskell.org]

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

On branch  : ghc-7.10
Link       : http://ghc.haskell.org/trac/ghc/changeset/d67b7842548209b5d0f6bc04afab84c84adbe70c/ghc

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

commit d67b7842548209b5d0f6bc04afab84c84adbe70c
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Fri Feb 13 23:10:18 2015 +0000

    Improve documentation of 'trace'
    
    See Trac #9795.
    
    (cherry picked from commit 7fdded4ed7e670e0c83d312b56a59b36c52913c9)


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

d67b7842548209b5d0f6bc04afab84c84adbe70c
 libraries/base/Debug/Trace.hs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/libraries/base/Debug/Trace.hs b/libraries/base/Debug/Trace.hs
index 389eb19..c81abbf 100644
--- a/libraries/base/Debug/Trace.hs
+++ b/libraries/base/Debug/Trace.hs
@@ -102,6 +102,10 @@ For example, this returns the value of @f x@ but first outputs the message.
 
 > trace ("calling f with x = " ++ show x) (f x)
 
+The 'trace' function evaluates the message (i.e. the first argument) completely
+before printing it; so if the message is not fully defined, none of it
+will be printed.
+
 The 'trace' function should /only/ be used for debugging, or for monitoring
 execution. The function is not referentially transparent: its type indicates
 that it is a pure function but it has the side effect of outputting the