[commit: ghc] master: Document the intricacies of ForallC variable quantification better (6330b0b)

[git at git.haskell.org]

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

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

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

commit 6330b0b0938bc7b27463b3bbfa0df661e4a966b1
Author: Ryan Scott <ryan.gl.scott at gmail.com>
Date:   Sat Sep 2 15:32:56 2017 -0400

    Document the intricacies of ForallC variable quantification better
    
    Summary:
    I recently (re-)discovered that `ForallC` quantifies different type variables
    depending on whether `GadtC` is present or not. This is an important
    enough gotcha where I feel like this fact should also be advertised in the
    `template-haskell` documentation itself, so this patch does just that.
    
    Test Plan: Read it
    
    Reviewers: goldfire, austin, bgamari
    
    Subscribers: rwbarton, thomie
    
    GHC Trac Issues: #13885
    
    Differential Revision: https://phabricator.haskell.org/D3880


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

6330b0b0938bc7b27463b3bbfa0df661e4a966b1
 .../template-haskell/Language/Haskell/TH/Syntax.hs | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
index aacc8c3..3087c69 100644
--- a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
+++ b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
@@ -1833,6 +1833,35 @@ data DecidedStrictness = DecidedLazy
                        | DecidedUnpack
         deriving (Show, Eq, Ord, Data, Generic)
 
+-- | A single data constructor.
+--
+-- The constructors for 'Con' can roughly be divided up into two categories:
+-- those for constructors with \"vanilla\" syntax ('NormalC', 'RecC', and
+-- 'InfixC'), and those for constructors with GADT syntax ('GadtC' and
+-- 'RecGadtC'). The 'ForallC' constructor, which quantifies additional type
+-- variables and class contexts, can surround either variety of constructor.
+-- However, the type variables that it quantifies are different depending
+-- on what constructor syntax is used:
+--
+-- * If a 'ForallC' surrounds a constructor with vanilla syntax, then the
+--   'ForallC' will only quantify /existential/ type variables. For example:
+--
+--   @
+--   data Foo a = forall b. MkFoo a b
+--   @
+--
+--   In @MkFoo@, 'ForallC' will quantify @b@, but not @a at .
+--
+-- * If a 'ForallC' surrounds a constructor with GADT syntax, then the
+--   'ForallC' will quantify /all/ type variables used in the constructor.
+--   For example:
+--
+--   @
+--   data Bar a b where
+--     MkBar :: (a ~ b) => c -> MkBar a b
+--   @
+--
+--   In @MkBar@, 'ForallC' will quantify @a@, @b@, and @c at .
 data Con = NormalC Name [BangType]       -- ^ @C Int a@
          | RecC Name [VarBangType]       -- ^ @C { v :: Int, w :: a }@
          | InfixC BangType Name BangType -- ^ @Int :+ a@