[commit: ghc] master: Add note on isSafeOverlap field. (6cc7d3f)

[git at git.haskell.org]

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

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

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

commit 6cc7d3f120d62d15ad6a2cc3393c3f744c93ff18
Author: David Terei <davidterei at gmail.com>
Date:   Mon Aug 19 16:00:55 2013 -0700

    Add note on isSafeOverlap field.


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

6cc7d3f120d62d15ad6a2cc3393c3f744c93ff18
 compiler/basicTypes/BasicTypes.lhs |    3 +++
 compiler/types/InstEnv.lhs         |   18 ++++++++++--------
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/compiler/basicTypes/BasicTypes.lhs b/compiler/basicTypes/BasicTypes.lhs
index 35b0ac5..838e368 100644
--- a/compiler/basicTypes/BasicTypes.lhs
+++ b/compiler/basicTypes/BasicTypes.lhs
@@ -362,6 +362,9 @@ instance Outputable RecFlag where
 %************************************************************************
 
 \begin{code}
+-- | The semantics allowed for overlapping instances for a particular
+-- instance. See Note [Safe Haskell isSafeOverlap] (in `InstEnv.lhs`) for a
+-- explanation of the `isSafeOverlap` field.
 data OverlapFlag
   -- | This instance must not overlap another
   = NoOverlap { isSafeOverlap :: Bool }
diff --git a/compiler/types/InstEnv.lhs b/compiler/types/InstEnv.lhs
index 18d67d8..6b6ddcd 100644
--- a/compiler/types/InstEnv.lhs
+++ b/compiler/types/InstEnv.lhs
@@ -582,14 +582,16 @@ lookupInstEnv (pkg_ie, home_ie) cls tys
         -- misleading (complaining of multiple matches when some should be
         -- overlapped away)
 
-    -- Safe Haskell: We restrict code compiled in 'Safe' mode from 
-    -- overriding code compiled in any other mode. The rational is
-    -- that code compiled in 'Safe' mode is code that is untrusted
-    -- by the ghc user. So we shouldn't let that code change the
-    -- behaviour of code the user didn't compile in 'Safe' mode
-    -- since that's the code they trust. So 'Safe' instances can only
-    -- overlap instances from the same module. A same instance origin
-    -- policy for safe compiled instances.
+    -- NOTE [Safe Haskell isSafeOverlap]
+    -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    -- We restrict code compiled in 'Safe' mode from overriding code
+    -- compiled in any other mode. The rational is that code compiled
+    -- in 'Safe' mode is code that is untrusted by the ghc user. So
+    -- we shouldn't let that code change the behaviour of code the
+    -- user didn't compile in 'Safe' mode since that's the code they
+    -- trust. So 'Safe' instances can only overlap instances from the
+    -- same module. A same instance origin policy for safe compiled
+    -- instances.
     check_safe match@(inst,_) others
         = case isSafeOverlap (is_flag inst) of
                 -- most specific isn't from a Safe module so OK