[commit: ghc] master: users-guide: Point out GNTD may require additional extensions (b876c1b)

[git at git.haskell.org]

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

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

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

commit b876c1bb5c8ccd73a203c0f94bac3cbb9c7e2d65
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Sun May 27 11:50:21 2018 -0400

    users-guide: Point out GNTD may require additional extensions
    
    As noted in #15073, GeneralizedNewtypeDeriving may produce code that
    uses extensions that do not directly appear in the code written by the
    user.  Make this clear in the users guide.
    
    [skip ci]
    
    Test Plan: Read it
    
    Reviewers: RyanGlScott
    
    Reviewed By: RyanGlScott
    
    Subscribers: fosskers, rwbarton, thomie, carter
    
    GHC Trac Issues: #15073
    
    Differential Revision: https://phabricator.haskell.org/D4701


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

b876c1bb5c8ccd73a203c0f94bac3cbb9c7e2d65
 docs/users_guide/glasgow_exts.rst | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 0de1a7a..01d65be 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -4666,7 +4666,7 @@ In this case the derived instance declaration is of the form ::
       instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
 
 Notice that, since ``Monad`` is a constructor class, the instance is a
-*partial application* of the new type, not the entire left hand side. We
+*partial application* of the newtype, not the entire left hand side. We
 can imagine that the type declaration is "eta-converted" to generate the
 context of the instance declaration.
 
@@ -4694,6 +4694,43 @@ 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.
 
+.. note::
+
+    It is sometimes necessary to enable additional language extensions when
+    deriving instances via :extension:`GeneralizedNewtypeDeriving`. For instance,
+    consider a simple class and instance using :extension:`UnboxedTuples`
+    syntax: ::
+
+        {-# LANGUAGE UnboxedTuples #-}
+
+        module Lib where
+
+        class AClass a where
+          aMethod :: a -> (# Int, a #)
+
+        instance AClass Int where
+          aMethod x = (# x, x #)
+
+    The following will fail with an "Illegal unboxed tuple" error, since the
+    derived instance produced by the compiler makes use of unboxed tuple syntax,
+    ::
+
+        {-# LANGUAGE GeneralizedNewtypeDeriving #-}
+
+        import Lib
+        
+        newtype Int' = Int' Int
+                     deriving (AClass)
+
+    However, enabling the :extension:`UnboxedTuples` extension allows the module
+    to compile. Similar errors may occur with a variety of extensions,
+    including:
+
+      * :extension:`UnboxedTuples`
+      * :extension:`TypeInType`
+      * :extension:`MultiParamTypeClasses`
+      * :extension:`FlexibleContexts`
+
 .. _precise-gnd-specification:
 
 A more precise specification