[commit: ghc] master: Improve documentation of -fwarn-redundant-constraints (2d15dc7)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2d15dc7fa58a6516e75502f511adf077b6360475/ghc

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

commit 2d15dc7fa58a6516e75502f511adf077b6360475
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Thu Jan 8 13:15:50 2015 +0000

    Improve documentation of -fwarn-redundant-constraints


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

2d15dc7fa58a6516e75502f511adf077b6360475
 docs/users_guide/using.xml | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 88dbdb7..499e486 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1418,10 +1418,11 @@ foreign import "&f" f :: FunPtr t
           <indexterm><primary><option>-fwarn-redundant-constraints</option></primary></indexterm>
           <indexterm><primary>redundant constraints, warning</primary></indexterm>
 
-          <para>Have the compiler warn about redundant constraints in a type signature. For
-          example
+          <para>Have the compiler warn about redundant constraints in a type signature. 
+          In particular:
           <itemizedlist>
           <listitem><para>
+          A redundant constraint within the type signature itself:
           <programlisting>
              f :: (Eq a, Ord a) => a -> a
           </programlisting>
@@ -1429,6 +1430,7 @@ foreign import "&f" f :: FunPtr t
           it is subsumed by the <literal>Ord a</literal> constraint.
           </para></listitem>
           <listitem><para>
+          A constraint in the type signature is not used in the code it covers:
           <programlisting>
              f :: Eq a => a -> a -> Bool
              f x y = True
@@ -1439,8 +1441,21 @@ foreign import "&f" f :: FunPtr t
           </itemizedlist>
           Similar warnings are given for a redundant constraint in an instance declaration.
           </para>
-
-          <para>This option is on by default.</para>
+          <para>This option is on by default.  As usual you can suppress it on a per-module basis
+          with <option>-fno-warn-redundant-constraints</option>.  Occasionally you may specifically
+          want a function to have a more constrained signature than necessary, perhaps to
+          leave yourself wiggle-rooom for changing the implementation without changing the
+          API.  In that case, you can suppress the warning on a per-function basis, using a
+          call in a dead binding.  For example:
+          <programlisting>
+             f :: Eq a => a -> a -> Bool
+             f x y = True
+                where
+                  _ = x == x  -- Suppress the redundant-constraint warning for (Eq a)
+          </programlisting>
+          Here the call to <literal>(==)</literal> makes GHC think that the <literal>(Eq a)</literal>
+          constraint is needed, so no warning is issued.
+          </para>
         </listitem>
       </varlistentry>