RFC: Declaration syntax

[lodinukal]

Rendered

[Dekkonot]

I do think if we're going to formalize this, it's worth revisiting the class declaration syntax. It's completely out of wack with the rest of the Luau type system, and we can probably do better.

Perhaps just giving it a similar syntax to the table types we already have instead of treating it like a block? As an example:

declare class Animal = {
  legs: number,
}

declare class Dog extends Animal = {
  tail_wagging: boolean,
}

This runs into problems with how functions are currently declared in classes, but I'm not sure there's a compelling reason to use the function keyword over just using a function type. In a world before read-only types, it probably made sense because it was a hidden way to differentiate 'properties' that you could set and static functions that you couldn't override, but we have a way to mark that in the type system now.

[aatxe]

How does it make it inconvenient to use? luau-lsp is using it right now.

[aatxe]

luau-lsp already uses declaration files as they are, so it's not really clear what we hope to actually gain here. the syntax of declaration files has been essentially unchanged since they were introduced, and it seems like the only thing this RFC has actually done is inspire conversation to make changes to it.

[aatxe]

Overall, my feeling about this RFC is that it doesn't actually do anything. The syntax for declaration files has been just as stable as the rest of Luau's syntax has been, and it's not clear what problem we're aiming to solve by having an RFC that just says it "formalizes" the syntax without actually formalizing the syntax at all. There's no formal characterization of the syntax present in this RFC in any form, and the motivation for it as-stated is completely imagined since it talks about luau-lsp using declaration files when it already does use them.

[qwitwa]

The benefit is it makes it your job to document it to a similar quality to the rest of the language. Luau-lsp is inside-baseball, it's hardly evidence for the absence of a problem. If it's so obvious what the declaration syntax is and does, please point me to the user facing docs that say exactly what "extends" tells the type checker the metatable situation is, or where read/write are valid. Stable does not just mean unchanging, but also shipped publicly, and right now the declaration syntax is not present at all in the syntax documentation. Aside from implementation in the form of docs, I see this partially as a political rfc whose adoption would, perfomatively by simply being rubber stamped, achieve its aims, to declare definition files as definitively the language team's responsibility.

[aatxe]

We don't need an RFC in order to document declaration files at all, just as we wouldn't need an RFC to write documentation for any other part of Luau's APIs. It's a valid criticism that they're not documented in any way, but that's not in-and-of-itself justification for an RFC, which is supposed to ultimately capture a specific addition to the language itself (or in some cases, a statement that we cannot or will not make a particular addition).

[aatxe]

In the context around this being proposed in the first place, there was also a bunch of discussion about things like "require support for definition files" and so forth, which kind of points at some of the problems or design considerations that come up if we want to treat this as a language feature in a proper sense.

Does accepting definition files just mean "here's a page on the website that shows you syntax and says you could use this with luau-analyze?" Does it mean something new behaviorally happens in the language? The RFC should be very explicit in its text about what exactly accepting it means, and doesn't mean, and the motivation should be clearly explained (e.g. better onboarding to using type definitions for runtime authors, as opposed to luau-lsp being able to use a thing that it already uses).

It's especially bad because the file extension that this RFC proposes is analogous to the extension that TypeScript uses for providing types for JavaScript, and people generally conceptualize that as "header files" rather than a foreign function interface to a different language. In Luau's case, the language gap between us and the foreign language is much greater, and, even without documentation, people today often ask about trying to use declare class to describe tables in Luau despite tables clearly not being a foreign C++ class.