Also, I think if we used an <abbr> (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr) for the tooltips it would still be accessible. We wouldn’t have as much control over styling that way, but I think accessibility is more important.

I think there's probably still an argument for printing the role declaration with the name comments even if we are also doing tooltips, if there's potentially a screenful of instances in between the (non-tooltip) role declaration and the data declaration.

That's true. If we're adding tooltip annotations then maybe we can just print the role declaration as it is, without the name comments then - similar to the way kind declarations are un-name-annotated.

Using the comments to indicate what type is what sounds good to me!

I also agree that we should do both.

I think that works too, yeah.

So, I propose keeping the line, but we could reduce it to a "single" line rather than the current "double" line above.

I don't see a problem with doing both, personally. I think if we are going to provide tooltips for type parameters, I'd like to include both their kind and their role in the tooltip.

The tests are all in...

Ok, I'll look at this later today.

The docs pipeline already includes inferred types in cases where types are not explicitly provided by getting them out of externs, and I think it should be possible to do the same for kinds.

Ok, so look at the externs code for help in figuring that out.

Can we get both the kind signature and the data type definition in the same <code> element so that there's no horizontal line in between them?

In some ways, I think the line is preferable as it clearly indicates what is the kind signature part and what is the type itself. Consider the following comparison of a type with a more complicated kind signature:

Maybe the role information could be integrated into the type declaration, as another alternative? When hovering over k / v in the data Map k v heading, something like that.

The thing I don't like about that it has poor discoverability, and is perhaps not very accessible... but it definitely appeals to me that we make the information available more contextually somehow. It could perhaps include the kind of the arguments similarly.

Ok, great, thanks. The double-thickness line in between the kind signature and the data type definition is a bit ugly, I think. Can we get both the kind signature and the data type definition in the same <code> element so that there's no horizontal line in between them?

I've fixed the merge conflict. Can we get another review here?

<details> <summary>Source code that has both kind and type comments</summary>

module Main where

import Prelude

-- | Kind doc
data DE1 :: forall k. k -> Type
-- | decl doc
-- |
-- | new line
-- | new line
data DE1 a = DE1

-- | Kind doc
type TE1 :: forall k. k -> Type
-- | decl doc
type TE1 a = Int

-- | Kind doc
newtype NE1 :: forall k. k -> Type
-- | decl doc
newtype NE1 a = NE1 Int

-- | Kind doc
class CE1 :: Type -> Constraint
-- | decl doc
class CE1 a where
  foo1 :: a -> String

instance CE1 String where
  foo1 s = s

</details>

<details> <summary>Source code that has only kind comments</summary>

module Main where

import Prelude

-- | Kind doc
data DE2 :: forall k. k -> Type
data DE2 a = DE2

-- | Kind doc
type TE2 :: forall k. k -> Type
type TE2 a = Int

-- | Kind doc
newtype NE2 :: forall k. k -> Type
newtype NE2 a = NE2 Int

-- | Kind doc
class CE2 :: Type -> Constraint
class CE2 a where
  foo2 :: a -> String

instance CE2 String where
  foo2 s = s

</details>

<details> <summary>Source code that has only type comments</summary>

module Main where

import Prelude

data DE3 :: forall k. k -> Type
-- | decl doc
data DE3 a = DE3

type TE3 :: forall k. k -> Type
-- | decl doc
type TE3 a = Int

newtype NE3 :: forall k. k -> Type
-- | decl doc
newtype NE3 a = NE3 Int

class CE3 :: Type -> Constraint
-- | decl doc
class CE3 a where
  foo3 :: a -> String

instance CE3 String where
  foo3 s = s

</details>

The tests are all in tests/TestDocs.hs, and they operate on the PureScript modules in tests/purs/docs/src. You'll probably want to add a new DocsAssertion constructor which asserts that a particular declaration has a kind signature matching the given kind, as well as a new DocsAssertionFailed constructor for when that assertion fails. You'll probably also want to add another module in the tests/purs/docs/src directory so that we can check that the docs do what we expect them both when kinds are inferred and when they are explicitly declared.

IIRC kind inference happens during type checking, which is after desugaring, so adjusting how we desugar for docs wouldn't help here. The docs pipeline already includes inferred types in cases where types are not explicitly provided by getting them out of externs, and I think it should be possible to do the same for kinds.

Oh, and we could do with some tests as well.

How would we test this? I didn't find any current examples that helped me know how I should proceed.

Also, it just occurred to me that I think we should include inferred kinds here as well. Does this branch do that already?

I'm not sure. Is that figured out in the desugaring pipeline? Perhaps the docs' version of that pipeline needs to be updated to include that pass if so?

Let me know if you need any help with the tests - I realise the docs tests framework is a quite a lot to take in.

Sounds good, thanks!

Perhaps that could be a special page on Pursuit?

To me, this feels like a better fit for the purescript/documentation repo, because that's where language documentation lives, and I think linking to that repl from Pursuit is fine. I think we already have documentation in there for roles too.

I agree with all of your reasoning about repeating the data type definition alongside the roles. I also think it's nice to reuse the language syntax so that you don't have to learn a separate syntax to understand what Pursuit is telling you. How about:

type role Map
  nominal -- k
  representational -- v

so that the code would still parse as a type role declaration, and the parameter names are displayed in comments alongside the role they correspond to?

Oh, and we could do with some tests as well.

I think we're nearly there, nice work :) Can you just share a screenshot or link for what the rendered HTML docs look like now please? Also, it just occurred to me that I think we should include inferred kinds here as well. Does this branch do that already?

Yeah, it is. I'll make the change. I think I'll also update other usages of the underlying value to say kind rather than type.

This is really a kind rather than a type, right? Maybe this field should be called kiKind?

I'm imagining the "?" link would take you to some docs explaining what roles are.

Perhaps that could be a special page on Pursuit? We could use a modified version of the answers in What is a Role?

This is slightly difficult, because roles are a slightly more advanced feature that most users shouldn't need to care about. I'd like to see if we can think of an alternative way of displaying role information which indicates that it's not as important as the type definition or kind signature. We should also make sure that inferred roles appear in the docs in the same way as declared roles, because the question of whether or roles are given explicitly or not is irrelevant to consumers of the package.

I think not having them at the top because they are a less-used feature makes sense. More important information should be shown first. However, by putting them on the bottom, it can be hard to know which role corresponds with which type parameter, especially if a type has a lot of instances that would force you to scroll up/down to see which role corresponds with which type parameter.

Could we perhaps redisplay the left-hand side of the type declaration alongside the role part? Something like your image's Role section above but it would show:

data Map k v
type role Map nominal representational

That fixes the scrolling issue I raise above.

However, I think a better breakdown would be to show the associations in a clearer manner (though I imagine it's harder to do)

data Map
  k = nominal
  v = representational

While most types won't have 2 or more type parameters, some (e.g. Halogen) could have many and figuring out what the 4th parameter's role is could be hard even with the first example I proposed above.

Here's another possibility, just as a discussion starting point:

I'm imagining the "?" link would take you to some docs explaining what roles are.

This is slightly difficult, because roles are a slightly more advanced feature that most users shouldn't need to care about. I'd like to see if we can think of an alternative way of displaying role information which indicates that it's not as important as the type definition or kind signature then I think we should do that. We should also make sure that inferred roles appear in the docs in the same way as declared roles, because the question of whether or roles are given explicitly or not is irrelevant to consumers of the package.

Summary

Roles were added in v0.14.0 with the work of the Coercible PRs. However, they do not currently appear in the HTML documentation.

Motivation

HTML docs should contain information on roles as that can affect whether coerce can be used or not. One cannot know whether the below type, Map, can be coerced unless they either read the source code or try to coerce a value via the REPL and see if they get a compiler error.

data Map k v = ---

type role Map nominal representational

Proposal

Map above does not export its constructors, so I don't think it's a good reference point for discussing where role annotations should appear in the docs. So, let's use Either instead for reference,

In #4100, kind signatures are displayed above the type's definition. For this situation, I think role annotations should be displayed under the type, following what we do in source code. Thus, the complete docs for a type that includes both a kind signature and a role annotation would look like this...

data Either :: Type -> Type -> Type
data Either l r
type role Either representational representational

... before we display anything else.

Right now, after display the type information (i.e. the content above), we then display the comments, then any constructors, and then any instances. Since the three entities above are each represented as three declarations in the AST, each with its own comments, we need to merge those comments together. In #4100, I "merged" the comments together by displaying kind signature comments first and then the type's comments, separating them with a newline. We could take a similar approach here. For example, given the following source code..

-- | kind declaration
data Either :: Type -> Type -> Type
-- | type declaration
data Either l r
-- | role declaration
type role Either representational representational

.. we would show the following in the docs

kind declaration
type declaration
role declaration

The implementation would follow the same approach used in #4100:

• ensure RoleDeclarations are not filtered out
• use the augment pass to add role information and merge its comments with existing comments (if any)
• render the role in the final HTML

Ok. I've just removed the last commit that made that change. I believe this PR should be ready to merge if there's no other issues with it.

Ok. Thanks for clarifying!

I think the Type ADT now has position info, though there are outstanding issues about improving (during desugaring)

I’d say define it once and don’t bother adding a note. It’s not really a big deal if it does end up being exported; we do coerce type names to class names and back in a bunch of places already, because that’s how type class desugaring works.

I think this would be unnecessarily cautious. Changing the syntax so that types can start with lowercase letters is almost certainly never going to happen, and the compiler should reject attempts to give foreign import data declarations separate kind signatures anyway (because the foreign import data declaration itself already contains a kind signature).