Commit 9d142622 authored by Simon Peyton Jones's avatar Simon Peyton Jones
Browse files

Improve documentation of standalone deriving (c.f. Trac #8851)

parent d246c62a
......@@ -3752,8 +3752,16 @@ GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by
</programlisting>
The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
<literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
Note the following points:
</para>
<para>
However, standalone deriving differs from a <literal>deriving</literal> clause in a number
of important ways:
<itemizedlist>
<listitem><para>The standalone deriving declaration does not need to be in the
same module as the data type declaration. (But be aware of the dangers of
orphan instances (<xref linkend="orphan-modules"/>).
</para></listitem>
<listitem><para>
You must supply an explicit context (in the example the context is <literal>(Eq a)</literal>),
exactly as you would in an ordinary instance declaration.
......@@ -3761,12 +3769,6 @@ exactly as you would in an ordinary instance declaration.
attached to a data type declaration, the context is inferred.)
</para></listitem>
<listitem><para>
A <literal>deriving instance</literal> declaration
must obey the same rules concerning form and termination as ordinary instance declarations,
controlled by the same flags; see <xref linkend="instance-decls"/>.
</para></listitem>
<listitem><para>
Unlike a <literal>deriving</literal>
declaration attached to a <literal>data</literal> declaration, the instance can be more specific
......@@ -3789,6 +3791,8 @@ declaration attached to a <literal>data</literal> declaration,
GHC does not restrict the form of the data type. Instead, GHC simply generates the appropriate
boilerplate code for the specified class, and typechecks it. If there is a type error, it is
your problem. (GHC will show you the offending code if it has a type error.)
</para>
<para>
The merit of this is that you can derive instances for GADTs and other exotic
data types, providing only that the boilerplate code does indeed typecheck. For example:
<programlisting>
......@@ -3811,6 +3815,16 @@ the side-conditions are necessarily more conservative, but any error message
may be more comprehensible.
</para>
</listitem>
</itemizedlist></para>
<para>
In other ways, however, a standalone deriving obeys the same rules as ordinary deriving:
<itemizedlist>
<listitem><para>
A <literal>deriving instance</literal> declaration
must obey the same rules concerning form and termination as ordinary instance declarations,
controlled by the same flags; see <xref linkend="instance-decls"/>.
</para></listitem>
<listitem>
<para>The stand-alone syntax is generalised for newtypes in exactly the same
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment