What does * (star) or other kinds mean in an instance list of haddock

Browsing the haddocks of various packages I often come along instance documentations that look like this (Control.Category):

Category k (Coercion k)
Category * (->)

or this (Control.Monad.Trans.Identity):

MonadTrans (IdentityT *)

What exactly here does the kind signature mean? It doesn't show up in the source, but I have already noticed that it seems to occur in modules that use the PolyKinds extension. I suspect it is probably like a TypeApplication but with a kind. So that e.g. the last example means that IdentityT is a monad transformer if it's first argument has kind *.

So my questions are:

Is my interpretation correct and what exactly does the kind signature refer to?
In the first Category instance, how am I supposed to know that k is a kind and not a type? Or do I just have to know the arity of Category?
What is the source code analog to this syntax?

I am not asking for an explanation of kinds.

Solution

To quote Richard Eisenberg’s recent post on the haskell-cafe mailing list:

Haddock struggles sometimes to render types with -XPolyKinds enabled. The problem is that GHC generally does not require kind arguments to be written and it does not print them out (unless you say -fprint-explicit-kinds). But Haddock, I believe, prints out kinds whenever -XPolyKinds is on. So the two different definitions are really the same: it's just that one module has -XPolyKinds and the other doesn't.

The * is the kind of ordinary types. So Int has kind * (we write Int :: *) while Maybe has kind * -> *. Typeable actually has kind forall k. k -> Constraint, meaning that it's polykinded. In the first snippet below, the * argument to Typeable instantiates k with *, because type variable a has kind *.

So yes, as you guessed, it has to do with PolyKinds. Haddock renders these poly-kinded types with a sort of “explicit kind application”. It just so happens that Category is poly-kinded, having the kind forall k. (k -> k -> *) -> Constraint, so Haddock renders the kind application alongside each instance.

In my opinion, this is a bug or misfeature of Haddock, since there is no equivalent source code analog as far as I know. It is confusing, and I don’t know of a better way to understand it than to recognize the way it usually manifests and visually infer what’s going on from the context.