purescript / pursuit

Website for hosting and searching PureScript API documentation
https://pursuit.purescript.org/
Other
170 stars 47 forks source link

Add an explanation on kind signatures appearing in documentation #434

Closed JordanMartinez closed 3 years ago

JordanMartinez commented 3 years ago

Follow up from this comment: https://github.com/purescript/purescript/pull/4119#issuecomment-869022915

Below is what I originally wrote for the changelog entry:


Previously, data/newtype/type/class declarations that have explicit kind signatures would not display those kind signatures in their documentation. For example, the two below types...

data PolyProxy :: forall k. k -> Type
data PolyProxy a = PolyProxy

data TypeProxy :: Type -> Type
data TypeProxy a = TypeProxy

... would only show the following information in their docs. One cannot be distinguished from another due to the missing kind signatures:

data PolyProxy a = PolyProxy

data TypeProxy a = TypeProxy

Now, these types' kind signatures are displayed above their declarations in their docs, similar to what one would see in the source code. The only exception to this are kind signatures whose kinds are "uninteresting" (covered below).

Moreover, declarations without explicit kind signatures will still display the kind signatures inferred by the compiler. For example, Foo's documentation will display the below (commented-out) inferred kind signature:

                                                {-
data Foo :: (Type -> Type) -> Type -> Type      -}
data Foo f a = Foo (f Int) a

However, a kind signature for both explicit and inferred kinds will not be displayed if that kind is considered "uninteresting." An "uninteresting" kind is one that follows this form:

Thus, both the Bar and Baz declarations below will not have their explicit and inferred kind signatures displayed in their docs.

data Bar :: Type -> Type -> Type
data Bar a b = Bar a b
                                                  {-
class Baz :: Type -> Type -> Constraint           -}
class Baz a b where
  doBaz :: a -> b -> String