Stream: ideas

Topic: doc type aliases

Brendan Hansknecht (Dec 24 2023 at 14:43):

Not sure if this has been covered before and I think it probably is just a wanted feature in docs, but type aliases exposed in docs should print out what they are an alias for.

For example, this doc is pretty useless cause it is missing this info:

Output : {
    stdout : List U8,
    stderr : List U8,
}

Not sure what we should do in the case of opaque types, but maybe in the printout just print <opaque> and not expose any type details.

Brendan Hansknecht (Dec 24 2023 at 14:49):

Also, not sure how to handle this, but a lot of modules are like Cmd.roc and InternalCmd.roc. which makes the type printout more complicated. If we do the naive thing, we would get this:

Error : InternalCommand.CommandErr

But in this case, we probably want the docs to say:

Error : [
    ExitCode I32,
    KilledBySignal,
    IOError Str,
]

Kevin Gillette (Dec 24 2023 at 15:11):

The <opaque> part could link to the tutorial section about opaque types, or have some brief explanation that "this type may only be meaningfully used by passing its values to functions which accept this type."

Brendan Hansknecht (Dec 24 2023 at 15:13):

Yeah, that works be nice

Kevin Gillette (Dec 24 2023 at 15:15):

Notably, the tutorial section on this is pretty brief, and further seems to be phrased from the perspective of a library creator ("create a type this way if you want to prevent anyone else from changing the internals") rather than also from the perspective of a library user ("if you see an opaque type, here's what they're meant for and how to use them"). The latter could be something that goes into a FAQ, but the tutorial section could benefit from some expansion (like what @ actually does and how to verbally pronounce it and :=).

Eli Dowling (Dec 26 2023 at 08:26):

This is also something we should think about in relation to our language server, there are cases where it might make sense to resolve aliases and present their contents when hovering over types. This is a complaint I have about hover docs and completion info in quite a number of languages that use a lot of domain modelling with types where often I actually want to know what the internal of a type are and it's a pain to actually get to them.

Perhaps the setting that would resolve aliases that aren't primitives like tuples or records and show their contents next to their names in type signatures.

Last updated: Jun 16 2026 at 16:19 UTC