Skip to content

Commit 40163dc

Browse files
xiangnanscuclaudecarsakiller
authored
docs(wiki): document generic classes in @Generic section (#144)
* docs(wiki): document generic classes in @Generic section The @Generic section predates v3.17.0 and did not mention that classes can declare type parameters beyond the index-signature examples. Add: - a sentence in the intro listing the v3.17.0 additions (generic class inheritance with type arguments, generic parameters in @overload, inline fun<T> function types in @field/@type) - an example of a generic class with fields and methods, including inheritance from an instantiated generic class, with a note on when type parameters are substituted - an example of the inline fun<T> generic function type All examples verified against lua-language-server 3.18.2 using --check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: escape backtick * update old generic example * add newline --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: carsakiller <carsakiller@gmail.com>
1 parent b3b7a36 commit 40163dc

1 file changed

Lines changed: 50 additions & 2 deletions

File tree

src/content/wiki/annotations.mdx

Lines changed: 50 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -647,7 +647,9 @@ local Numbers = {}
647647

648648
### @generic
649649

650-
Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (<code>`</code>) will capture the string value from the argument and infer the named class/type as the generic type. [Generics are still WIP](https://github.com/LuaLS/lua-language-server/issues/1861).
650+
Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (<code>\`</code>) will capture the string value from the argument and infer the named class/type as the generic type. [Generics are still WIP](https://github.com/LuaLS/lua-language-server/issues/1861).
651+
652+
Since `v3.17.0`, classes can declare type parameters (e.g. `Box<T>`), classes can inherit from an instantiated generic class (e.g. `IntegerBox: Box<integer>`), generic type parameters work in [`@overload`](#overload) annotations, and `fun<T>(...)` inline generic function types are supported in [`@field`](#field) and [`@type`](#type) annotations.
651653

652654
**Syntax**
653655

@@ -727,12 +729,58 @@ See [Issue #734](https://github.com/LuaLS/lua-language-server/issues/734#issueco
727729
---@type Dictionary<boolean>
728730
local dict = {}
729731

730-
-- no warning despite assigning a string
732+
-- Warning: assigning string to boolean
731733
dict["foo"] = "bar?"
732734

733735
dict["correct"] = true
734736
```
735737

738+
</Accordion>
739+
<Accordion>
740+
<span slot="summary">Generic Class with Fields and Methods</span>
741+
742+
```lua
743+
---@class Box<T>
744+
---@field value T
745+
---@field get fun(self: Box<T>): T
746+
747+
---@type Box<integer>
748+
local box
749+
750+
-- `v` is an integer here
751+
local v = box.value
752+
753+
-- `got` is an integer here
754+
local got = box:get()
755+
756+
---A class can also inherit from an instantiated generic class (v3.17.0+)
757+
---@class IntegerBox: Box<integer>
758+
759+
---@type IntegerBox
760+
local ibox
761+
762+
-- `v2` and `got2` are integers here as well
763+
local v2 = ibox.value
764+
local got2 = ibox:get()
765+
```
766+
767+
Note: for the type parameter to be substituted through inheritance, members must be declared as `---@field` entries in the class annotation block. A method declared separately (e.g. `---@return T` above `function Box:m() end`) only has `T` substituted when the receiver's type is the instantiated generic class itself (e.g. a value of type `Box<integer>`), not when the method is reached through an inheriting class like `IntegerBox`.
768+
769+
</Accordion>
770+
<Accordion>
771+
<span slot="summary">Inline Generic Function Type (v3.17.0+)</span>
772+
773+
```lua
774+
---@class Utils
775+
---@field identity fun<T>(value: T): T
776+
777+
---@type Utils
778+
local utils
779+
780+
-- `s` is a string here
781+
local s = utils.identity("hello")
782+
```
783+
736784
</Accordion>
737785

738786
### @meta

0 commit comments

Comments
 (0)