From ca6793d6d71ac4c62699bfac5be82c790e7d4d49 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:28:18 -0500 Subject: [PATCH 1/5] Initial Commit --- docs/syntax-attributes-for-everything.md | 94 ++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/syntax-attributes-for-everything.md diff --git a/docs/syntax-attributes-for-everything.md b/docs/syntax-attributes-for-everything.md new file mode 100644 index 000000000..350ddbc4a --- /dev/null +++ b/docs/syntax-attributes-for-everything.md @@ -0,0 +1,94 @@ +# Attributes Everywhere + +## Summary + +Allows [Attributes](./syntax-attributes-functions.md) to be applied to almost anything in Luau. + +## Motivation + +Currently attributes can only be applied to functions, this means types cannot be marked as [`@deprecated`](./syntax-attribute-functions-deprecated.md). +Nor can variables or table fields be marked as [`@deprecated`](./syntax-attribute-functions-deprecated.md). + +## Design + +Note: With this RFC the internals for attributes will be able to state they can be applied to only certain bits of syntax, so one can't apply [`@native`](./syntax-attribute-functions-native.md) to a type or variable and have it work. Although this RFC does not state how this would be done in luaus internals. + +The following list proposes how attributes should be attached to each bit of syntax in luau (except functions and comments): + +### Variables + +This exists as it could be useful for if for instance a function is defined as a local variable and then exported: + +```luau +@[deprecated { reason = "cat is a more modern API"}] +local function get_cat_sound() + return "meow" +end + +return table.freeze({ + get_cat_sound = get_cat_sound, + cat = "meow", +}) +``` + +### Tables + +```luau +local pet_sounds = { + @deprecated cat = "meow" +} + +@deprecated module.dog = "woof" + +@deprecated +module.parrot = "cracker, now" + +return table.freeze(pet_sounds) +``` + +Note: If the value of a entry has attributes, those will be merged with the attributes defined on the entry. +With the attributes on the entry having priority over the attributes on the value. + +```luau +@[deprecated { reason = "cat is a more modern API"}] +local function get_cat_sound() + return "meow" +end + +local module = table.freeze({ + @[deprecated{ use = "cat" }] get_cat_sound = get_cat_sound, + cat = "meow" +}) + +-- DeprecatedApi: Member 'get_cat_sound' is deprecated, use 'cat' instead Luau(22) +module.get_cat_sound() +``` + +### Types + +Types work similarly to [Variables](#variables) and [Tables](#tables), except being types. + +```luau +@[deprecated{ use = "PetSounds" }] +type pet_sounds = { + parrot: "cracker, now", + dog: "woof", + cat: "meow", +} + +@deprecated +type Puppy = "whimper" + +type PetSounds = { + -- Just like with tables, entries have their attributes merged with + @deprecated{ use = "dog" } puppy: Puppy, + dog: "bark", + cat: "mrrp", +} +``` + +## Drawbacks + +Allowing attributes everywhere, would be added complexity to the language. Although would be more inline with what a user would expect/want, as its currently odd as a user that types can't be marked as deprecated. + +This RFC does not define how attributes should be able to be added to comments, although there is no clear use case for this currently. From e413bf62e5785a8d740273ddd39f1db60cf2a3c0 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:38:34 -0500 Subject: [PATCH 2/5] oopsies --- docs/syntax-attributes-for-everything.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax-attributes-for-everything.md b/docs/syntax-attributes-for-everything.md index 350ddbc4a..6dc4e4b33 100644 --- a/docs/syntax-attributes-for-everything.md +++ b/docs/syntax-attributes-for-everything.md @@ -80,7 +80,7 @@ type pet_sounds = { type Puppy = "whimper" type PetSounds = { - -- Just like with tables, entries have their attributes merged with + -- Just like with tables, entries have their attributes merged with the values attributes. @deprecated{ use = "dog" } puppy: Puppy, dog: "bark", cat: "mrrp", From 47f9cc624d6c1a1691ccb4258cc318f7a975c083 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:47:23 -0500 Subject: [PATCH 3/5] fix variables --- docs/syntax-attributes-for-everything.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/syntax-attributes-for-everything.md b/docs/syntax-attributes-for-everything.md index 6dc4e4b33..9843a0639 100644 --- a/docs/syntax-attributes-for-everything.md +++ b/docs/syntax-attributes-for-everything.md @@ -17,17 +17,15 @@ The following list proposes how attributes should be attached to each bit of syn ### Variables -This exists as it could be useful for if for instance a function is defined as a local variable and then exported: +This exists as it could be useful for if for instance a constant is defined as a local variable and then exported: ```luau -@[deprecated { reason = "cat is a more modern API"}] -local function get_cat_sound() - return "meow" -end +@[deprecated { reason = "dog is a more modern API"}] +local puppy = "whimper" return table.freeze({ - get_cat_sound = get_cat_sound, - cat = "meow", + puppy = puppy, + dog = "woof", }) ``` From 119533a0c8f901de78dedad9e0b65ed31f5ee483 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Wed, 10 Dec 2025 11:16:57 -0500 Subject: [PATCH 4/5] rename --- ...syntax-attributes-for-types-variables-table-fields.md} | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) rename docs/{syntax-attributes-for-everything.md => syntax-attributes-for-types-variables-table-fields.md} (84%) diff --git a/docs/syntax-attributes-for-everything.md b/docs/syntax-attributes-for-types-variables-table-fields.md similarity index 84% rename from docs/syntax-attributes-for-everything.md rename to docs/syntax-attributes-for-types-variables-table-fields.md index 9843a0639..e08631bd8 100644 --- a/docs/syntax-attributes-for-everything.md +++ b/docs/syntax-attributes-for-types-variables-table-fields.md @@ -1,8 +1,8 @@ -# Attributes Everywhere +# Allow attributes to be used on types, variables, and table fields ## Summary -Allows [Attributes](./syntax-attributes-functions.md) to be applied to almost anything in Luau. +Allows [Attributes](./syntax-attributes-functions.md) to be applied to types, variables, and table fields in Luau. ## Motivation @@ -87,6 +87,4 @@ type PetSounds = { ## Drawbacks -Allowing attributes everywhere, would be added complexity to the language. Although would be more inline with what a user would expect/want, as its currently odd as a user that types can't be marked as deprecated. - -This RFC does not define how attributes should be able to be added to comments, although there is no clear use case for this currently. +Allowing attributes to be on types, variables, and table fields, would be added complexity to the language. Although would be more inline with what a user would expect/want, as its odd from the perspective of a user that currently types can't be marked as deprecated. From 8f2c88f5489bdc031e185bc5aa845beb1059be72 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Wed, 10 Dec 2025 12:00:29 -0500 Subject: [PATCH 5/5] sync --- ...ibutes-for-types-variables-table-fields.md | 54 +++++++++++++++---- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/docs/syntax-attributes-for-types-variables-table-fields.md b/docs/syntax-attributes-for-types-variables-table-fields.md index e08631bd8..1fa721901 100644 --- a/docs/syntax-attributes-for-types-variables-table-fields.md +++ b/docs/syntax-attributes-for-types-variables-table-fields.md @@ -20,7 +20,7 @@ The following list proposes how attributes should be attached to each bit of syn This exists as it could be useful for if for instance a constant is defined as a local variable and then exported: ```luau -@[deprecated { reason = "dog is a more modern API"}] +@[deprecated { use = "dog"}] local puppy = "whimper" return table.freeze({ @@ -29,6 +29,28 @@ return table.freeze({ }) ``` +Although this will cause the return in the module to be linted, but this lint won't be passed on to consumers of the module: + +Module: + +```luau +-- DeprecatedApi: Variable 'puppy' is deprecated, use 'dog' instead Luau(22) +return table.freeze({ + puppy = puppy, + dog = "woof", +}) +``` + +Consumer: + +```luau +-- No lint occurs on the import +local module = require("@module") + +-- DeprecatedApi: Member 'puppy' is deprecated, use 'dog' instead Luau(22) +print(module.puppy) +``` + ### Tables ```luau @@ -44,8 +66,10 @@ module.parrot = "cracker, now" return table.freeze(pet_sounds) ``` -Note: If the value of a entry has attributes, those will be merged with the attributes defined on the entry. -With the attributes on the entry having priority over the attributes on the value. +If the value of a field has attributes, those will be merged with the attributes defined on the field. +With the attributes on the field having priority over the attributes on the value. +For example: if both the value and the field have a `@deprecated` attribute, the `@deprecated` attribute on the value will be ignored. +With the `@deprecated` attribute on the field being used instead. ```luau @[deprecated { reason = "cat is a more modern API"}] @@ -53,6 +77,13 @@ local function get_cat_sound() return "meow" end +-- DeprecatedApi: Function 'get_cat_sound' is deprecated, cat is a more modern API Luau(22) +local bad_module = table.freeze({ + get_cat_sound = get_cat_sound, +}) + +-- No lint occurs, because the @deprecated attribute of the 'get_cat_sound' function has been overridden +-- by the @deprecated attribute of the field 'get_cat_sound'. local module = table.freeze({ @[deprecated{ use = "cat" }] get_cat_sound = get_cat_sound, cat = "meow" @@ -67,16 +98,17 @@ module.get_cat_sound() Types work similarly to [Variables](#variables) and [Tables](#tables), except being types. ```luau -@[deprecated{ use = "PetSounds" }] -type pet_sounds = { - parrot: "cracker, now", - dog: "woof", - cat: "meow", -} - @deprecated type Puppy = "whimper" +-- DeprecatedApi: Type 'Puppy' is deprecated Luau(22) +type CanineSounds = { + puppy: Puppy, + dog: "woof", +} + +-- No lint occurs, because the @deprecated attribute of the type 'Puppy' has been overridden +-- by the @deprecated attribute of the field 'puppy'. type PetSounds = { -- Just like with tables, entries have their attributes merged with the values attributes. @deprecated{ use = "dog" } puppy: Puppy, @@ -85,6 +117,8 @@ type PetSounds = { } ``` +Although type declarations can also have attributes directly after the `=`, + ## Drawbacks Allowing attributes to be on types, variables, and table fields, would be added complexity to the language. Although would be more inline with what a user would expect/want, as its odd from the perspective of a user that currently types can't be marked as deprecated.