Clarify users' guide section on GeneralizedNewtypeDeriving
authorRyan Scott <ryan.gl.scott@gmail.com>
Fri, 27 May 2016 18:12:57 +0000 (14:12 -0400)
committerRyan Scott <ryan.gl.scott@gmail.com>
Fri, 27 May 2016 18:13:05 +0000 (14:13 -0400)
Summary:
It seemed to imply that GHC was generating infelicitous code when it
actually wasn't. Fixes #12047.

Reviewers: hvr, bgamari, austin

Reviewed By: austin

Subscribers: thomie, Iceland_jack

Differential Revision: https://phabricator.haskell.org/D2273

GHC Trac Issues: #12047

docs/users_guide/glasgow_exts.rst

index a8a7f8f..5860878 100644 (file)
@@ -3814,16 +3814,26 @@ Generalising the deriving clause
 GHC now permits such instances to be derived instead, using the flag
 :ghc-flag:`-XGeneralizedNewtypeDeriving`, so one can write ::
 
-      newtype Dollars = Dollars Int deriving (Eq,Show,Num)
+      newtype Dollars = Dollars { getDollars :: Int } deriving (Eq,Show,Num)
 
 and the implementation uses the *same* ``Num`` dictionary for
-``Dollars`` as for ``Int``. Notionally, the compiler derives an instance
-declaration of the form ::
+``Dollars`` as for ``Int``. In other words, GHC will generate something that
+resembles the following code ::
 
       instance Num Int => Num Dollars
 
-which just adds or removes the ``newtype`` constructor according to the
-type.
+and then attempt to simplify the ``Num Int`` context as much as possible.
+GHC knows that there is a ``Num Int`` instance in scope, so it is able to
+discharge the ``Num Int`` constraint, leaving the code that GHC actually
+generates ::
+
+      instance Num Dollars
+
+One can think of this instance being implementated with the same code as the
+``Num Int`` instance, but with ``Dollars`` and ``getDollars`` added wherever
+necessary in order to make it typecheck. (In practice, GHC uses a somewhat
+different approach to code generation. See the :ref:`precise-gnd-specification`
+section below for more details.)
 
 We can also derive instances of constructor classes in a similar way.
 For example, suppose we have implemented state and failure monad
@@ -3876,6 +3886,8 @@ declarations are treated uniformly (and implemented just by reusing the
 dictionary for the representation type), *except* ``Show`` and ``Read``,
 which really behave differently for the newtype and its representation.
 
+.. _precise-gnd-specification:
+
 A more precise specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~