From: simonpj <unknown>
Date: Fri, 29 Apr 2005 11:08:51 +0000 (+0000)
Subject: [project @ 2005-04-29 11:08:51 by simonpj]
X-Git-Tag: Initial_conversion_from_CVS_complete~638
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=f6c5ce7209e827a689bb7162f46dbf3a2736934c;p=ghc-hetmet.git

[project @ 2005-04-29 11:08:51 by simonpj]
Document improvements in overlap handling
---

diff --git a/ghc/docs/users_guide/flags.xml b/ghc/docs/users_guide/flags.xml
index 0bb4400..c4aa7cd 100644
--- a/ghc/docs/users_guide/flags.xml
+++ b/ghc/docs/users_guide/flags.xml
@@ -545,7 +545,8 @@
 	    </row>
 	    <row>
 	      <entry><option>-fallow-incoherent-instances</option></entry>
-	      <entry>Enable incoherent instances</entry>
+	      <entry>Enable incoherent instances.  
+	      Implies <option>-fallow-overlapping-instances</option> </entry>
 	      <entry>dynamic</entry>
 	      <entry><option>-fno-allow-incoherent-instances</option></entry>
 	    </row>
diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml
index 3d52399..404db44 100644
--- a/ghc/docs/users_guide/glasgow_exts.xml
+++ b/ghc/docs/users_guide/glasgow_exts.xml
@@ -1762,7 +1762,8 @@ these declarations:
   instance context3 => C Int [a]   where ...  -- (C)
   instance context4 => C Int [Int] where ...  -- (D)
 </programlisting>
-The instances (A) and (B) match the constraint <literal>C Int Bool</literal>, but (C) and (D) do not.  When matching, GHC takes
+The instances (A) and (B) match the constraint <literal>C Int Bool</literal>, 
+but (C) and (D) do not.  When matching, GHC takes
 no account of the context of the instance declaration
 (<literal>context1</literal> etc).
 GHC's default behaviour is that <emphasis>exactly one instance must match the
@@ -1795,10 +1796,33 @@ GHC will instead pick (C), without complaining about
 the problem of subsequent instantiations.
 </para>
 <para>
-Because overlaps are checked and reported lazily, as described above, you need
-the <option>-fallow-overlapping-instances</option> in the module that <emphasis>calls</emphasis> 
-the overloaded function, rather than in the module that <emphasis>defines</emphasis> it.</para>
-
+The willingness to be overlapped or incoherent is a property of 
+the <emphasis>instance declaration</emphasis> itself, controlled by the
+presence or otherwise of the <option>-fallow-overlapping-instances</option> 
+and <option>-fallow-incoherent-instances</option> flags when that mdodule is
+being defined.  Neither flag is required in a module that imports and uses the
+instance declaration.  Specifically, during the lookup process:
+<itemizedlist>
+<listitem><para>
+An instance declaration is ignored during the lookup process if (a) a more specific
+match is found, and (b) the instance declaration was compiled with 
+<option>-fallow-overlapping-instances</option>.  The flag setting for the
+more-specific instance does not matter.
+</para></listitem>
+<listitem><para>
+Suppose an instance declaration does not matche the constraint being looked up, but
+does unify with it, so that it might match when the constraint is further 
+instantiated.  Usually GHC will regard this as a reason for not committing to
+some other constraint.  But if the instance declaration was compiled with
+<option>-fallow-incoherent-instances</option>, GHC will skip the "does-it-unify?" 
+check for that declaration.
+</para></listitem>
+</itemizedlist>
+All this makes it possible for a library author to design a library that relies on 
+overlapping instances without the library client having to know.
+</para>
+<para>The <option>-fallow-incoherent-instances</option> flag implies the
+<option>-fallow-overlapping-instances</option> flag, but not vice versa.
 </sect3>
 
 <sect3>