Improving presentation of types and signatures in the docs

[joshi-monster]

Improving the presentation of type signatures and definitions makes the documentation of every single Gleam library nicer and easier to learn.

Gleams' docs print types and type signatures in multiple places; sometimes, it uses the TypeAst to generate the docs (so the docs will show the types as written in the code), while sometimes, it will instead format the concrete type names the type-checker figured out.

In my opinion, both ways it currently works can lead to confusion while reading the docs:

• The TypeAst might contain private aliases, which as a reader of the docs I don't necessarily know about
• The resolved types are shown unqualified, making it hard to know at a glance where a type comes from. It also suffers from the same problems as the TypeAst, where it sometimes will show the names of private types.

We've discussed this a few times on Discord, and I foolishly, being young, excited, and ignorant, wrote some code first before actually asking what/if something should be done here. So this is me asking! 😄 I'll give my thoughts on all of these questions, but please don't read this as "I have all the anwers" - those are just my opinions and suggestions, and it is never my intention to come across like that. Basically all of this is very much subjective. I'm looking forward to hearing all of your take on those as well!

How should type names be formatted presented?

In general, I think the types names that are shown should always be

• uniquely identifiable
• discoverable through/in the documentation
• match the names a consumer of the library would expect

To this end, I believe showing the resolved types from the type checker here is preferable in general to showing the type the library author typed. Types in the same module may be shown unqualified, if they don't collide with a type from the prelude - those are already unique and I believe it's clear from the context that they come from the current module. In other cases, I suggest showing the type the same way a consumer would use them by default, qualified with the last bit of their module path:

// current:
pub fn generate(options: Options) -> Result(Nil, List(Error))

// suggested:
// Options is unqualified because it's declared in the same module
// generate is the default qualified name for embeds/generate
pub fn generate(options: Options) -> Result(Nil, List(generate.Error))

I think a nice addition here would be to be able to hover type names to see their fully-qualified name, link to the documentation of this type.

Private types and type aliases

This still means that often, internal types might be shown. A common pattern used in packages is to define types in an internal module, and then use a public type alias in a public module to "re-export" them.

Currently, this is not that big of a problems because of 2 things:

• Types printed using the TypeAst will show the public type alias if the library author used that one
• Types printed using the resolved type will show the unqualified internal type name, which most often matches the name of the public alias

With the changes above, this would lead to signatures like this:

pub fn div(attrs: List(vdom.Attribute(a)), children: List(vdom.Element(a))) -> vdom.Element(a)

where vdom is an internal module, even though the library author used publicly exported type aliases.

I think a good ruleset would be:

• Show public type aliases the same way other public types are presented.
• If a type alias is private (for example because the library author imported some type using as), it gets expanded until a public type is found
• If no public type can be printed, this should be an error/warning.

pub fn div(attrs: List(attribute.Attribute(a)), children: List(element.Element(a))) -> element.Element(a)

Should type variable names be shown?

The names chosen for type variables often help to understand what is what, especially if there are multiple type variables in a signature. In that way, they work similarly in my opinion to the names of function variables, which are already shown and also serve documentation purposes. For example, I think these are easier to read than the latter:

fn map_error(result: Result(ok, err), with on_error: fn(err) -> err2) -> Result(ok, err2)
pub fn application(
  init: fn(flags) -> #(model, effect.Effect(msg)),
  update: fn(model, msg) -> #(model, effect.Effect(msg)),
  view: fn(model) -> element.Element(msg),
) -> App(flags, model, msg)

// vs:

fn map_error(result: Result(a, b), with on_error: fn(b) -> c) -> Result(a, c)
pub fn application(
  init: fn(a) -> #(b, Effect(c)),
  update: fn(b, c) -> #(model, Effect(c)),
  view: fn(b) -> Element(c),
) -> App(a, b, c)

If no type annotation is present, the name of the type variable from the type definition side might be used.
If a private type alias is used using type variables, those names could be "copied over" into their expanded form.

Thanks for reading! 😔

[lpil]

Hello! Thanks for waiting, catching up after my holiday still.

This is a fantastic write up and I think you're spot on with your reasoning. This would be a huge improvement to the quality of the generated documentation and I'd love to see this implemented.

In order to make it easier to implement and review I think it would be worth breaking it into chunks rather than attempting to delivery it all in a single pull request which could get large and get stuck in reivew-hell. If you have ideas for how to break this down it would be good to have issues for each of them. Otherwise we can have one issue and the implementer can figure it out.

Thanks again! Fantastic work!

[joshi-monster]

Hi, thanks a lot!! 💜

Sorry I haven't found the time and energy to look at this again sooner (this is a me problem 😄).

I tried to split things up here:

Show type alias names in function signatures

I think that one is reasonably simple and independent from the others, so it could probably be split off into its own thing.

Add alias information to type_::Type

There already was a change recently to show types from other packages fully qualified, so the problem I talk about with internal types is already visible in some cases. I think showing internal types from other modules would worsen this by a lot.

Since we want to show the concrete types and not the names the module author used, being able to access alias information in the type_::Type almost feels like a prerequisite for the other stuff, and would also enable the compiler to emit warnings again. I think you said in the past that this is not true, and I also think that the LSP has some way of showing type aliases, so there's a good chance I'm completely wrong here! 🙂

The goal here is to ignore/skip over them in all places by default for now, but be able to specially handle them when appropriate, like not unwrapping them when printing types, and potentially improve error messages in the future.

Always use the the resolved types in the docs, print qualified type names

After aliases can be explicitly handled when needed, I think we can print qualified types without accidentally leaking implementation details/internal modules, as well as probably bring the warning back when trying to publish a package.

Add links and annotations

Again, we would want to ideally show the resolved public aliases here, since public types are exposed in the documentation and can be linked to.

[lpil]

being able to access alias information in the TypeAst almost feels like a prerequisite for the other stuff

Could you expand on what this means? I don't understand, sorry. TypeAst currently only has the names written (aliases), it doesn't know anything about the actual types.

Always use the TypeAst in the docs, print qualified type names

This is what we do currently, and it results in us showing code that may not be meaningful or even possible for the documentation reader. I thought this is what we wanted to move away from?

[joshi-monster]

Could you expand on what this means? I don't understand, sorry. TypeAst currently only has the names written (aliases), it doesn't know anything about the actual types.

You are right, my bad, I should have double-checked this one more time, totally confused the 2 myself. I meant gleam_core::type_::Type; I've updated my comment above.