Render imported types with module qualifiers in documentation

[michallepicki]

Given a module that imports code from another module, and public types (or functions) using that type, e.g.

import gleam/otp/node.{Node}
import gleam/otp/actor.{StartError}

pub type ApplicationStartMode {
  Normal
  Takeover(Node)
  Failover(Node)
}

pub fn worker(
  start: fn(argument) -> Result(Sender(msg), StartError),
) -> ChildSpec(msg, argument, argument) {
// ...

Currently types in documentation are rendered as present in code. For someone reading the module documentation without broader knowledge of the library, it is hard to see where a type comes from without reaching into module source code. For the library author, it is an inconvenience to always specify a module even if code compiles.

The gleam docs command could automatically add module qualifiers when rendering documentation. (Some time in the future, it could also render a clickable link)

[lpil]

Great suggestion! Thank you.

[lpil]

One question I have, how do we show namespaced modules in type sigs?

import one/two/three.{Type}

pub type MyType = Type

Here the type is one/two/three.Type and we'd want that qualified in some fashion, but one/two/three.Type isn't valid Gleam syntax.

Perhaps that's OK but it would be good to see some mock-up screenshots (can just edit the HTML in browser) before we commit to an implementation.

[michallepicki]

What about something like this? Last part of the imported module in the type, full module name on mouse hover (span title attribute)

[lpil]

That's a great idea! Let's do that

[JohnDoneth]

I've been working on rendering clickable links to types in the documentation as mentioned here but have hit a couple blockers.

• We don't currently have the library name in the type information.
• When it comes to the stdlib/builtin types, they don't contain module paths.

If Float had the module path ["gleam", "float"] with the library name "gleam_stdlib". Then we'd have all the information necessary to generate links. Assuming everything is on Hex we could generate: https://hexdocs.pm/gleam_stdlib/gleam/float/#Float

For library types, we already have module path, but are lacking the library name needed to generate the full link to the hexdocs package.

Would it be fine to hard-code those module paths in the static type information and add an additional field to specify the library name to types?

Would love any thoughts you have.

[michallepicki]

Louis will decide but here are my 2 cents: The package would be mostly needed for hyperlinks? I was thinking it may be easier to implement this without hyperlinks for now.

I also think it might be better to not render anything special for the built-in types. They come from a special auto-imported module gleam and are not a part of the gleam_stdlib - they are only type aliases re-exported from there. Adding gleam. before every String or List seems noisy and unnecessary. But I do have a few related thoughts:

• Since recently there could be a type called the same that shadows one of them in code (docs). It would be grand if we could handle that correctly
• When someone imports and uses aliases, e.g. the prelude types re-exported from stdlib, probably point to where they are imported from?