From 1187d6c4b95d39907f9a6bd35ec4505a911f8251 Mon Sep 17 00:00:00 2001 From: Kyle Kovacs Date: Wed, 12 Nov 2025 13:55:12 -0800 Subject: [PATCH 1/2] docs: explain backtick generic capture better Based on discussion here: https://github.com/LuaLS/lua-language-server/issues/1861#issuecomment-3518024894 --- src/content/wiki/annotations.mdx | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/src/content/wiki/annotations.mdx b/src/content/wiki/annotations.mdx index 863c747..f3f2776 100644 --- a/src/content/wiki/annotations.mdx +++ b/src/content/wiki/annotations.mdx @@ -646,7 +646,7 @@ local Numbers = {} ### @generic -Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (`) will capture the value and use it for the type. [Generics are still WIP](https://github.com/LuaLS/lua-language-server/issues/1861). +Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (`) will capture the string value from the caller and use it for the type. [Generics are still WIP](https://github.com/LuaLS/lua-language-server/issues/1861). **Syntax** @@ -680,16 +680,22 @@ local v3, v4 = Generic(10) ```Lua ---@class Vehicle -local Vehicle = {} -function Vehicle:drive() end ---@generic T ----@param class `T` # the type is captured using `T` ----@return T # generic type is returned -local function new(class) end +---@param class `T` # the type is captured +---@return T # The return type will be the type identified by the string value of the 'class' argument +local function newWithCapture(class) end + +-- obj1 has type 'Vehicle' here, because "Vehicle" is captured from the first argument +local obj1 = newWithCapture("Vehicle") + +---@generic T +---@param class T # the type is NOT captured +---@return T # The return type will be the same as the type of the 'class' argument +local function newWithoutCapture(class) end --- obj: Vehicle -local obj = new("Vehicle") +-- obj2 has type 'string' here, because the first argument is a string +local obj2 = newWithoutCapture("Vehicle") ``` From bc22f839e63e5320acb026697aba632092dffea4 Mon Sep 17 00:00:00 2001 From: Kyle Kovacs Date: Thu, 13 Nov 2025 10:33:33 -0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: carsakiller --- src/content/wiki/annotations.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/wiki/annotations.mdx b/src/content/wiki/annotations.mdx index f3f2776..23a5d2e 100644 --- a/src/content/wiki/annotations.mdx +++ b/src/content/wiki/annotations.mdx @@ -646,7 +646,7 @@ local Numbers = {} ### @generic -Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (`) will capture the string value from the caller and use it for the type. [Generics are still WIP](https://github.com/LuaLS/lua-language-server/issues/1861). +Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (`) 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). **Syntax** @@ -683,18 +683,18 @@ local v3, v4 = Generic(10) ---@generic T ---@param class `T` # the type is captured ----@return T # The return type will be the type identified by the string value of the 'class' argument +---@return T # The return type will be the class/type inferred from the string value of the `class` argument local function newWithCapture(class) end --- obj1 has type 'Vehicle' here, because "Vehicle" is captured from the first argument +-- obj1 has type `Vehicle` here, because "Vehicle" is captured from the provided argument local obj1 = newWithCapture("Vehicle") ---@generic T ---@param class T # the type is NOT captured ----@return T # The return type will be the same as the type of the 'class' argument +---@return T # The return type will be the same as the type of the `class` argument local function newWithoutCapture(class) end --- obj2 has type 'string' here, because the first argument is a string +-- obj2 has type `string` here, because the provided argument is a string local obj2 = newWithoutCapture("Vehicle") ```