[commit: ghc] master: Document OVERLAP pragmas. (99c2823)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/99c28232115702003d4c2728bc44e09bd60993f2/ghc

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

commit 99c28232115702003d4c2728bc44e09bd60993f2
Author: Iavor S. Diatchki <iavor.diatchki at gmail.com>
Date:   Sat Jul 19 16:54:35 2014 -0700

    Document OVERLAP pragmas.


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

99c28232115702003d4c2728bc44e09bd60993f2
 docs/users_guide/glasgow_exts.xml | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 9acb56f..336798c 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -5022,6 +5022,18 @@ and <option>-XIncoherentInstances</option>
 flags are dynamic flags, and can be set on a per-module basis, using
 an <literal>LANGUAGE</literal> pragma if desired (<xref linkend="language-pragma"/>).</para>
 
+<para>
+In addition, it is possible to specify the overlap behavior for individual
+instances with a pragma, written immediately after the
+<literal>instance</literal> keyword.  The pragma may be one of:
+<literal>OVERLAP</literal>, <literal>NO_OVERLAP</literal>,
+or <literal>INCOHERENT</literal>.  An explicit pragma on an instance
+takes precedence over the default specified with a flag or
+a <literal>LANGUAGE</literal> pragma.  For example, an instance marked with
+<literal>{-# NO_OVERLAP #-}</literal> will be marked as non-overlapping,
+even if the module contains <literal>{-# LANGUAGE OverlappingInstances #-}</literal>.
+</para>
+
 
 <para>
 The <option>-XOverlappingInstances</option> flag instructs GHC to loosen
@@ -5037,7 +5049,8 @@ The <option>-XIncoherentInstances</option> flag implies the
 <para>
 A more precise specification is as follows.
 The willingness to be overlapped or incoherent is a property of
-the <emphasis>instance declaration</emphasis> itself, controlled by the
+the <emphasis>instance declaration</emphasis> itself, controlled by
+iether an explicit pragma, or the
 presence or otherwise of the <option>-XOverlappingInstances</option>
 and <option>-XIncoherentInstances</option> flags when that instance declaration is
 being compiled.  Now suppose that, in some client module, we are searching for an instance of the
@@ -10771,6 +10784,22 @@ data T = T {-# NOUNPACK #-} !(Int,Int)
      </para>
 </sect2>
 
+<sect2 id="overlap-pragma">
+<title>OVERLAP, NO_OVERLAP, and INCOHERENT pragmas</title>
+<para>
+The <literal>OVERLAP</literal>, <literal>NO_OVERLAP</literal>, and
+<literal>INCOHERENT</literal> pragmas are used to specify the overlap
+behavior for individual instances, as described in Section
+<xref linkend="instance-overlap"/>.  They take precedence over the behavior
+specified with the corresponding <literal>LANGUAGE</literal> pragmas.
+The pragmas are written immediately after the <literal>instance</literal>
+keyword.  For example:
+</para>
+<programlisting>
+instance {-# OVERLAP #-} C t where ...
+</programlisting>
+</sect2>
+
 </sect1>
 
 <!--  ======================= REWRITE RULES ======================== -->