Refine incomplete-pattern checks (Trac #4905)

[ghc-hetmet.git] / docs / users_guide / using.xml

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index be82322..18e9622 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -990,9 +990,11 @@ ghc -c Foo.hs</screen>
          <emphasis>not</emphasis> enabled by <option>-Wall</option>
          are
             <option>-fwarn-tabs</option>,
+            <option>-fwarn-incomplete-uni-patterns</option>,
             <option>-fwarn-incomplete-record-updates</option>,
             <option>-fwarn-monomorphism-restriction</option>,
-            <option>-fwarn-unused-do-bind</option>, and
+            <option>-fwarn-unrecognised-pragmas</option>,
+            <option>-fwarn-auto-orphans</option>,
             <option>-fwarn-implicit-prelude</option>.</para>
        </listitem>
       </varlistentry>
@@ -1175,6 +1177,21 @@ foreign import "&amp;f" f :: FunPtr t
       </varlistentry>
 
       <varlistentry>
+        <term><option>-fwarn-identities</option>:</term>
+       <listitem>
+          <indexterm><primary><option>-fwarn-identities</option></primary></indexterm>
+          <para>Causes the compiler to emit a warning when a Prelude numeric
+            conversion converts a type T to the same type T; such calls
+            are probably no-ops and can be omitted.  The functions checked for
+            are: <literal>toInteger</literal>,
+            <literal>toRational</literal>,
+            <literal>fromIntegral</literal>,
+            and <literal>realToFrac</literal>.
+          </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>-fwarn-implicit-prelude</option>:</term>
         <listitem>
           <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
@@ -1200,26 +1217,40 @@ foreign import "&amp;f" f :: FunPtr t
       </varlistentry>
 
       <varlistentry>
-       <term><option>-fwarn-incomplete-patterns</option>:</term>
+       <term><option>-fwarn-incomplete-patterns</option>, 
+              <option>-fwarn-incomplete-uni-patterns</option>, 
        <listitem>
          <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
+         <indexterm><primary><option>-fwarn-incomplete-uni-patterns</option></primary></indexterm>
          <indexterm><primary>incomplete patterns, warning</primary></indexterm>
          <indexterm><primary>patterns, incomplete</primary></indexterm>
 
-         <para>Similarly for incomplete patterns, the function
+          <para>The option <option>-fwarn-incomplete-patterns</option> warns 
+            about places where
+           a pattern-match might fail at runtime.  
+          The function
           <function>g</function> below will fail when applied to
           non-empty lists, so the compiler will emit a warning about
           this when <option>-fwarn-incomplete-patterns</option> is
-          enabled.</para>
-
+          enabled.
 <programlisting>
 g [] = 2
 </programlisting>
-
-         <para>This option isn't enabled by default because it can be
+         This option isn't enabled by default because it can be
           a bit noisy, and it doesn't always indicate a bug in the
           program.  However, it's generally considered good practice
-          to cover all the cases in your functions.</para>
+          to cover all the cases in your functions, and it is switched 
+          on by <option>-W</option>.</para>
+
+          <para>The flag <option>-fwarn-incomplete-uni-patterns</option> is
+          similar, except that it
+          applies only to lambda-expressions and pattern bindings, constructs
+         that only allow a single pattern:
+<programlisting>
+h = \[] -> 2
+Just k = f y
+</programlisting>
+          </para>
        </listitem>
       </varlistentry>
 
@@ -2194,9 +2225,8 @@ statements or clauses.
   <filename>.hcr</filename>. The Core format is described in <ulink url="../../core.pdf">
   <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, 
   and sample tools
-  for manipulating Core files (in Haskell) are in the GHC source distribution 
-  directory under <literal>utils/ext-core</literal>.  
-  Note that the format of <literal>.hcr</literal> 
+  for manipulating Core files (in Haskell) are available in the
+  <ulink url="http://hackage.haskell.org/package/extcore">extcore package on Hackage</ulink>.  Note that the format of <literal>.hcr</literal>
   files is <emphasis>different</emphasis> from the Core output format that GHC generates 
   for debugging purposes (<xref linkend="options-debugging"/>), though the two formats appear somewhat similar.</para>