-
Notifications
You must be signed in to change notification settings - Fork 92
Description
Currently, the Luau type system backend does not yet have real support for documentation comments on types or fields, and there is also no mechanism for retaining docs comments through type functions. However, in practice, docs comments (---) on table fields are preserved by luau-lsp when used with generics, allowing them to appear in tooltips. Unfortunately, when using type functions (such as utility types like ReadOnly and Class(my custom utility type function for better metatable class types)), these comments are not retained.
It would be very helpful if documentation comments could also be preserved for type function results, just like with generics.
Motivation/Use case
When you pass a documented type into a generic, the field docs are shown in tooltips as expected:
type T = {
--- apple count
apple: number,
}
type Processed = Generic<T>
local a: Processed = {} :: any
a.apple -- docs comment appears ('apple count')However, if you pass the same type through a type function, the docs comment is lost:
type T = {
--- apple count
apple: number,
}
type Processed = TypeFunc<T> -- e.g. typeforge.ReadOnly<T>
local a: Processed = {} :: any
a.apple -- docs comment does **not** appearIt would be great if docs comments could be preserved for type function results in the same way as generics. This would make utility types much more usable and keep field documentation visible for downstream consumers.
One potential challenge here is that the output of a type function might differ significantly from its input, or map fields in non-trivial ways—so it's not always clear which (if any) docs comments from the input type should be propagated.
If you have a better idea or an alternative approach for this problem, please let me know.