diff --git a/rfcs/annotations.md b/rfcs/annotations.md new file mode 100644 index 00000000..15e5185e --- /dev/null +++ b/rfcs/annotations.md @@ -0,0 +1,69 @@ +# Function annotations + +## Summary + +Reserve a syntax for being able to add special qualities to areas such as function declarations. + +## Motivation + +By supporting annotations, we are able to forwards compatibly add new behavior to functions and other statements, and potentially support user specified decorators. + +## Design + +Let's suppose we want to add the equivalent to [`#[must_use]`](https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute). We *could* try to create some special syntax for that, like so: + +```lua +local function giveValue(): number mustuse +``` + +This would work in the moment, but let's suppose we also now want to add something like [`#[inline]`](https://doc.rust-lang.org/reference/attributes/codegen.html#the-inline-attribute). We *could* make a special syntax for that as well, like... + +```lua +local inline function giveValue(): number mustuse +``` + +Then suppose we want something like [`noexcept`](https://en.cppreference.com/w/cpp/language/noexcept_spec), we could make a special syntax for that too, but you should be seeing the issue by now: all of these additions are not obvious readability wins, and increase burden of implementation with more parser edge cases. + +Instead, this RFC proposes a general syntax of `@name` as an annotation syntax. + +Our previous example might instead look like: + +```lua +@must_use +@inline +local function giveValue(): number +``` + +Annotations would support the following syntax: + +``` +annotation = '@' NAME [ '(' exp ')' ] +``` + +This annotation would apply to the entire following statement or expression. This would let us support something like: + +```lua +@allow("unused_variable") +local x = 1 + +local x = { + @allow("undefined_variable") + notDefined, +} +``` + +While not specified in this RFC, this could also pave the way for user defined decorators, and the syntax is function-like accordingly. + +This RFC does not propose any annotations, just that the syntax be reserved for future use cases. + +## Drawbacks + +We might not have enough valid use cases to justify adding this to the language itself. Similarly, this might encourage more feature bloat. + +On that note, it might be easiest to afford feature specific syntax. For instance, the `mustuse` qualifier, or something like `MustUse`. + +## Alternatives + +We could limit this only to function declarations. + +We could decide to not support user defined decorators, and simplify the syntax accordingly--`@allow("undefined_variable")` could become `@allow(undefined_variable)`, for instance, knowing there will never be any ambiguity in whether or not this is referencing a variable.