Skip to content

Preserve docs comments for type function results #1249

@jiwonz

Description

@jiwonz

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** appear

It 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions