gleam icon indicating copy to clipboard operation
gleam copied to clipboard

WIP: Links in type signatures

Open joshi-monster opened this issue 6 months ago • 1 comments

I feel like this has already gotten quite big, so I thought I'd stop at the early point before you say it's all unreasonable anyways and I waste a bunch of time :D

First: I cannot "just" generate links, since highlight.js will not allow them..

Instead, all code relevant to type/function/constant signatures is highlighted at compile time, and types are always printed using the type_::pretty::Printer in the docs. It introduces a new variant to the Document, and a new DocumentWriter trait that can react on them. Since it looked like the documents formatter goes to great length to avoid being recursive, I've also tried to do that. This introduces another new Cmd type that gets used instead of the list of (indent, mode, doc) triples, and consequently changes a lot of types around in format. Just doing recursion would basically get rid of all of that.

Overall, this allows for all signatures (with small extensions all parseable Gleam code) to be highlighted by the compiler directly, without relying on Javascript. This could potentially also be used to add colors/links to error messages, or annotate all examples in the docs as well.

If a resolved type (ignoring aliases) is publicly exposed, a link to its documentation will be generated as well. Versions are currently ignored. Ignoring aliases means that a common pattern doesn't work currently (lustre for example does this with every type), where an internal type is re-exported using a type alias.

Questions

  • What about tests? There are existing tests for the docs output which I updated, but generally, I'm a bit lost what you would expect.
  • What to do about the alias thing?

fix #3461 #828

joshi-monster avatar Aug 01 '24 19:08 joshi-monster