[commit: ghc] new-typeable: User's guide documentation for Typeable (334b686)

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : new-typeable

http://hackage.haskell.org/trac/ghc/changeset/334b686daf3f0bda9db3c940efc5926ca3840342

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

commit 334b686daf3f0bda9db3c940efc5926ca3840342
Author: Jose Pedro Magalhaes <[email protected]>
Date:   Wed Nov 28 11:40:30 2012 +0000

    User's guide documentation for Typeable

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

 docs/users_guide/flags.xml        |   14 ++++++++++++++
 docs/users_guide/glasgow_exts.xml |   26 +++++++++++++-------------
 docs/users_guide/using.xml        |   18 ++++++++++++++++--
 3 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 0e7ed23..8b8f07f 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1065,6 +1065,12 @@
             <entry><option>-XNoDeriveDataTypeable</option></entry>
           </row>
           <row>
+            <entry><option>-XAutoDeriveTypeable</option></entry>
+            <entry>Automatically derive Typeable instances for every datatype and type class declaration.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-XNoAutoDeriveTypeable</option></entry>
+          </row>
+          <row>
             <entry><option>-XDeriveGeneric</option></entry>
             <entry>Enable <link linkend="deriving-typeable">deriving for the Generic class</link>.</entry>
             <entry>dynamic</entry>
@@ -1444,6 +1450,14 @@
             <entry><option>-fno-warn-warnings-deprecations</option></entry>
           </row>
 
+          <row>
+            <entry><option>-fwarn-typeable-instances</option></entry>
+            <entry>warn if there are any handwritten <literal>Typeable</literal>
+                   instances (see <xref linkend="deriving-typeable"/>)</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-warn-typeable-instances</option></entry>
+          </row>
+
         </tbody>
       </tgroup>
     </informaltable>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index aac9994..ffcf14c 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3338,19 +3338,19 @@ GHC extends this list with several more classes that may be automatically derive
 <literal>Typeable</literal>, and <literal>Data</literal>, defined in the library
 modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively.
 </para>
-<para>An instance of <literal>Typeable</literal> can only be derived if the
-data type has seven or fewer type parameters, all of kind <literal>*</literal>.
-The reason for this is that the <literal>Typeable</literal> class is derived using the scheme
-described in
-<ulink url="http://research.microsoft.com/%7Esimonpj/papers/hmap/gmap2.ps">
-Scrap More Boilerplate: Reflection, Zips, and Generalised Casts
-</ulink>.
-(Section 7.4 of the paper describes the multiple <literal>Typeable</literal> classes that
-are used, and only <literal>Typeable1</literal> up to
-<literal>Typeable7</literal> are provided in the library.)
-In other cases, there is nothing to stop the programmer writing a <literal>TypeableX</literal>
-class, whose kind suits that of the data type constructor, and
-then writing the data type instance by hand.
+<para>Since GHC 7.8.1, <literal>Typeable</literal> is kind-polymorphic (see
+<xref linkend="kind-polymorphism"/>) and can be derived for any datatype and
+type class. Instances for datatypes can be derived by attaching a 
+<literal>deriving Typeable</literal> clause to the datatype declaration, or by
+using standalone deriving (see <xref linkend="stand-alone-deriving"/>).
+Instances for type classes can only be derived using standalone deriving.
+Additionally, <option>-XAutoDeriveTypeable</option> will trigger the generation
+of derived <literal>Typeable</literal> instances for every datatype and type
+class declaration in the module it is used.
+</para>
+<para>
+Also since GHC 7.8.1, handwritten (ie. not derived) instances of
+<literal>Typeable</literal> are forbidden, and will be ignored with a warning.
 </para>
 </listitem>
 
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index c3a1366..a7dc7f2 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -955,8 +955,9 @@ test.hs:(5,4)-(6,7):
     <option>-fwarn-missing-methods</option>,
     <option>-fwarn-lazy-unlifted-bindings</option>,
     <option>-fwarn-wrong-do-bind</option>,
-    <option>-fwarn-unsupported-calling-conventions</option>, and
-    <option>-fwarn-dodgy-foreign-imports</option>.  The following
+    <option>-fwarn-unsupported-calling-conventions</option>,
+    <option>-fwarn-dodgy-foreign-imports</option>, and
+    <option>-fwarn-typeable-instances</option>.  The following
     flags are
     simple ways to select standard &ldquo;packages&rdquo; of warnings:
     </para>
@@ -1663,6 +1664,19 @@ f "2"    = 2
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>-fwarn-typeable-instances</option>:</term>
+        <listitem>
+          <indexterm><primary><option>-fwarn-typeable-instances</option></primary></indexterm>
+          <indexterm><primary>typeable instances, warning</primary></indexterm>
+
+          <para>Report handwritten (ie. not derived) instances of the
+          <literal>Typeable</literal> class. These are ignore by the compiler;
+          only derived instances of <literal>Typeable</literal> are allowed.
+          </para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
 
     <para>If you're feeling really paranoid, the