Commit 6330b0b0 authored by Ryan Scott's avatar Ryan Scott

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
parent 590e7376
......@@ -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@.
--
-- * 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@.
data Con = NormalC Name [BangType] -- ^ @C Int a@
| RecC Name [VarBangType] -- ^ @C { v :: Int, w :: a }@
| InfixC BangType Name BangType -- ^ @Int :+ a@
......
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