[commit: ghc] master: Better documentation for AnyK (7dfc320)

[José Pedro Magalhães]

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/7dfc32005a55aed0dffaac679df788906f6f462f

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

commit 7dfc32005a55aed0dffaac679df788906f6f462f
Author: Jose Pedro Magalhaes <jpm at cs.uu.nl>
Date:   Tue Nov 15 15:20:01 2011 +0000

    Better documentation for AnyK

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

 compiler/prelude/TysPrim.lhs    |    4 ++--
 compiler/prelude/primops.txt.pp |   25 +++++++++++++++++--------
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/compiler/prelude/TysPrim.lhs b/compiler/prelude/TysPrim.lhs
index 5cb07a1..1223d46 100644
--- a/compiler/prelude/TysPrim.lhs
+++ b/compiler/prelude/TysPrim.lhs
@@ -650,7 +650,7 @@ The type constructor Any of kind forall k. k -> k has these properties:
     the code generator, because the code gen may *enter* a data value
     but never enters a function value. 
 
-  * It is used to instantiate otherwise un-constrained type variables of kind *
+  * It is used to instantiate otherwise un-constrained type variables
     For example   	length Any []
     See Note [Strangely-kinded void TyCons]
 
@@ -665,7 +665,7 @@ Any, but at the kind level. For example:
   type instance Length [] = Zero
 
 Length is kind-polymorphic, and when applied to the empty (promoted) list it
-will be supplied the kind AnyL: Length AnyK [].
+will have the kind Length AnyK [].
 
 Note [Strangely-kinded void TyCons]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index fa3a287..204dce2 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -1849,7 +1849,7 @@ pseudoop   "lazy"
 
 	Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
 
-primtype Any a
+primtype Any k
 	{ The type constructor {\tt Any} is type to which you can unsafely coerce any
 	lifted type, and back. 
 
@@ -1872,16 +1872,25 @@ primtype Any a
 	application is required, but there is no constraint on the
 	choice.  In this situation GHC uses {\tt Any}:
 
-	{\tt length Any ([] Any)}
+	{\tt length (Any *) ([] (Any *))}
 
-	Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
-	This is a bit like tuples.   We define a couple of useful ones here,
-	and make others up on the fly.  If any of these others end up being exported
-	into interface files, we'll get a crash; at least until we add interface-file
-	syntax to support them. }
+        Note that {\tt Any} is kind polymorphic, and takes a kind {\tt k} as its
+        first argument. The kind of {\tt Any} is thus {\tt forall k. k -> k}.}
 
 primtype AnyK
-	{ JPM Todo }
+        { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
+        kind polymorphic setting, a similar example to the length of the empty
+        list can be given at the type level:
+
+        {\tt type family Length (l :: [k]) :: Nat}
+        {\tt type instance Length [] = Zero}
+
+        When {\tt Length} is applied to the empty (promoted) list it will have
+        the kind {\tt Length AnyK []}.
+
+        {\tt AnyK} is currently not exported and cannot be used directly, but
+        you might see it in debug output from the compiler.
+        }
 
 pseudoop   "unsafeCoerce#"
    a -> b