[commit: ghc] master: Document #15079 in the users' guide (bc9a838)

[git at git.haskell.org]

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

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

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

commit bc9a838a27f40a6008e127d9105981713abe774b
Author: Ryan Scott <ryan.gl.scott at gmail.com>
Date:   Thu Jun 7 13:29:12 2018 -0400

    Document #15079 in the users' guide
    
    Trac #15079 revealed an interesting limitation in the interaction
    between variable visibility and higher-rank kinds. We (Richard and I)
    came to the conclusion that this is an acceptable (albeit surprising)
    limitation, so this documents in the users' guide to hopefully eliminate
    some confusion for others in the future.
    
    Test Plan: Read it
    
    Reviewers: goldfire, bgamari
    
    Reviewed By: bgamari
    
    Subscribers: rwbarton, thomie, carter
    
    GHC Trac Issues: #15079
    
    Differential Revision: https://phabricator.haskell.org/D4803


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

bc9a838a27f40a6008e127d9105981713abe774b
 docs/users_guide/glasgow_exts.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 95b2256..98786e6 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -9130,6 +9130,24 @@ In this redefinition, we give an explicit kind for ``(:~~:)``, deferring the cho
 of ``k2`` until after the first argument (``a``) has been given. With this declaration
 for ``(:~~:)``, the instance for ``HTestEquality`` is accepted.
 
+Another difference between higher-rank kinds and types can be found in their
+treatment of inferred and user-specified type variables. Consider the following
+program: ::
+
+  newtype Foo (f :: forall k. k -> Type) = MkFoo (f Int)
+  data Proxy a = Proxy
+
+  foo :: Foo Proxy
+  foo = MkFoo Proxy
+
+The kind of ``Foo``'s parameter is ``forall k. k -> Type``, but the kind of
+``Proxy`` is ``forall {k}. k -> Type``, where ``{k}`` denotes that the kind
+variable ``k`` is to be inferred, not specified by the user. (See
+:ref:`visible-type-application` for more discussion on the inferred-specified
+distinction). GHC does not consider ``forall k. k -> Type`` and
+``forall {k}. k -> Type`` to be equal at the kind level, and thus rejects
+``Foo Proxy`` as ill-kinded.
+
 Constraints in kinds
 --------------------