fix: resolve generics in overloads, fun<T> syntax, and @param self T patterns

- Add support for @Generic T in @overload annotations (#723)
- Parse fun<T>(x: T): T syntax in @field and @type annotations (#1170)
- Fix methods with @Generic T and @param self T to resolve return type
  to receiver's concrete type (e.g., List<number>:identity() returns
  List<number> instead of unknown) (#1000)
- Add comprehensive test cases for all generic patterns

Author: ian-pascoe

changelog.md

@@ -5,6 +5,9 @@
 * `FIX` Generic class inheritance with type arguments now works correctly (e.g., `class Bar: Foo<integer>`) [#1929](https://github.com/LuaLS/lua-language-server/issues/1929)
 * `FIX` Method return types on generic classes now resolve correctly (e.g., `Box<string>:getValue()` returns `string`) [#1863](https://github.com/LuaLS/lua-language-server/issues/1863)
 * `FIX` Self-referential generic classes no longer cause infinite expansion in hover display [#1853](https://github.com/LuaLS/lua-language-server/issues/1853)
+* `FIX` Generic type parameters now work in `@overload` annotations [#723](https://github.com/LuaLS/lua-language-server/issues/723)
+* `NEW` Support `fun<T>` syntax for inline generic function types in `@field` and `@type` annotations [#1170](https://github.com/LuaLS/lua-language-server/issues/1170)
+* `FIX` Methods with `@generic T` and `@param self T` now correctly resolve return type to the receiver's concrete type (e.g., `List<number>:identity()` returns `List<number>`) [#1000](https://github.com/LuaLS/lua-language-server/issues/1000)
 
 ## 3.16.4
 `2025-12-25`

script/parser/guide.lua

@@ -177,7 +177,7 @@ local childMap = {
     ['doc.generic.object'] = {'generic', 'extends', 'comment'},
     ['doc.vararg']         = {'vararg', 'comment'},
     ['doc.type.array']     = {'node'},
-    ['doc.type.function']  = {'#args', '#returns', 'comment'},
+    ['doc.type.function']  = {'#args', '#returns', '#signs', 'comment'},
     ['doc.type.table']     = {'#fields', 'comment'},
     ['doc.type.literal']   = {'node'},
     ['doc.type.arg']       = {'name', 'extends'},

script/parser/luadoc.lua

@@ -523,6 +523,8 @@ local function  parseTypeUnitFunction(parent)
         args    = {},
         returns = {},
     }
+    -- Parse optional generic params: fun<T, V>(...)
+    typeUnit.signs = parseSigns(typeUnit)
     if not nextSymbolOrError('(') then
         return nil
     end
@@ -617,6 +619,51 @@ local function  parseTypeUnitFunction(parent)
         end
     end
     typeUnit.finish = getFinish()
+    -- Bind local generics from fun<T, V> to type names within this function
+    if typeUnit.signs then
+        local generics = {}
+        for _, sign in ipairs(typeUnit.signs) do
+            generics[sign[1]] = sign
+        end
+        local function bindTypeNames(obj)
+            if not obj then return end
+            if obj.type == 'doc.type.name' and generics[obj[1]] then
+                obj.type = 'doc.generic.name'
+                obj.generic = generics[obj[1]]
+            elseif obj.type == 'doc.type' and obj.types then
+                for _, t in ipairs(obj.types) do
+                    bindTypeNames(t)
+                end
+            elseif obj.type == 'doc.type.array' then
+                bindTypeNames(obj.node)
+            elseif obj.type == 'doc.type.table' and obj.fields then
+                for _, field in ipairs(obj.fields) do
+                    bindTypeNames(field.name)
+                    bindTypeNames(field.extends)
+                end
+            elseif obj.type == 'doc.type.sign' then
+                bindTypeNames(obj.node)
+                if obj.signs then
+                    for _, s in ipairs(obj.signs) do
+                        bindTypeNames(s)
+                    end
+                end
+            elseif obj.type == 'doc.type.function' then
+                for _, arg in ipairs(obj.args) do
+                    bindTypeNames(arg.extends)
+                end
+                for _, ret in ipairs(obj.returns) do
+                    bindTypeNames(ret)
+                end
+            end
+        end
+        for _, arg in ipairs(typeUnit.args) do
+            bindTypeNames(arg.extends)
+        end
+        for _, ret in ipairs(typeUnit.returns) do
+            bindTypeNames(ret)
+        end
+    end
     return typeUnit
 end
 
@@ -1857,7 +1904,8 @@ local function bindGeneric(binded)
         or doc.type == 'doc.type'
         or doc.type == 'doc.class'
         or doc.type == 'doc.alias'
-        or doc.type == 'doc.field' then
+        or doc.type == 'doc.field'
+        or doc.type == 'doc.overload' then
             guide.eachSourceType(doc, 'doc.type.name', function (src)
                 local name = src[1]
                 if generics[name] then

script/vm/compiler.lua

@@ -1550,18 +1550,120 @@ local function bindReturnOfFunction(source, mfunc, index, args)
     if not returnObject then
         return
     end
+
+    local resolveArgs = args
+    if source.func and source.func.type == 'getmethod' then
+        local receiver = source.func.node
+        if receiver then
+            resolveArgs = { receiver }
+            if args then
+                for i = 2, #args do
+                    resolveArgs[#resolveArgs + 1] = args[i]
+                end
+            end
+        end
+    end
+
     local returnNode = vm.compileNode(returnObject)
+
+    local selfGenericResolved = nil
+    if source.func and source.func.type == 'getmethod' and mfunc.type == 'function' and mfunc.bindDocs then
+        local receiver = source.func.node
+        if receiver then
+            local receiverNode = vm.compileNode(receiver)
+            local selfGenericName = nil
+            for _, doc in ipairs(mfunc.bindDocs) do
+                if doc.type == 'doc.param' and doc.param and doc.param[1] == 'self' then
+                    if doc.extends then
+                        for _, typeUnit in ipairs(doc.extends.types or {}) do
+                            if typeUnit.type == 'doc.generic.name' then
+                                selfGenericName = typeUnit[1]
+                                break
+                            end
+                        end
+                    end
+                    break
+                end
+            end
+            if selfGenericName then
+                local filteredNode = vm.createNode()
+                for item in receiverNode:eachObject() do
+                    if item.type == 'doc.type.sign'
+                    or (item.type == 'global' and item.cate == 'type')
+                    or item.type == 'doc.type.table'
+                    or item.type == 'doc.type.array' then
+                        filteredNode:merge(item)
+                    end
+                end
+                if not filteredNode:isEmpty() then
+                    selfGenericResolved = { [selfGenericName] = filteredNode }
+                else
+                    selfGenericResolved = { [selfGenericName] = receiverNode }
+                end
+            end
+        end
+    end
+
     for rnode in returnNode:eachObject() do
         if rnode.type == 'generic' then
-            returnNode = rnode:resolve(guide.getUri(source), args)
+            if selfGenericResolved and rnode.sign then
+                local resolved = rnode.sign:resolve(guide.getUri(source), resolveArgs) or {}
+                for k, v in pairs(selfGenericResolved) do
+                    resolved[k] = v
+                end
+                local protoNode = vm.compileNode(rnode.proto)
+                local result = vm.createNode()
+                for nd in protoNode:eachObject() do
+                    if nd.type == 'global' or nd.type == 'variable' then
+                        result:merge(nd)
+                    else
+                        local clonedObject = vm.cloneObject(nd, resolved)
+                        if clonedObject then
+                            result:merge(vm.compileNode(clonedObject))
+                        end
+                    end
+                end
+                if protoNode:isOptional() then
+                    result:addOptional()
+                end
+                returnNode = result
+            else
+                returnNode = rnode:resolve(guide.getUri(source), resolveArgs)
+            end
             break
         end
     end
 
-    -- Handle method calls on generic class instances
-    -- When calling b:getValue() where b is Box<string>, resolve T to string
+    if mfunc.type == 'function' then
+        local hasUnresolvedGeneric = false
+        for rnode in returnNode:eachObject() do
+            if rnode.type == 'doc.generic.name' and not rnode._resolved then
+                hasUnresolvedGeneric = true
+                break
+            end
+        end
+        if hasUnresolvedGeneric then
+            local sign = vm.getSign(mfunc)
+            if sign and resolveArgs and #resolveArgs > 0 then
+                local resolved = sign:resolve(guide.getUri(source), resolveArgs)
+                if resolved and next(resolved) then
+                    local newReturnNode = vm.createNode()
+                    for rnode in returnNode:eachObject() do
+                        local cloned = vm.cloneObject(rnode, resolved)
+                        if cloned then
+                            newReturnNode:merge(vm.compileNode(cloned))
+                        else
+                            newReturnNode:merge(rnode)
+                        end
+                    end
+                    returnNode = newReturnNode
+                end
+            end
+        end
+    end
+
     local call = source.parent
-    if call and call.type == 'call' then
+    if not selfGenericResolved and call and call.type == 'call' then
         local callNode = call.node
         if callNode and (callNode.type == 'getmethod' or callNode.type == 'getfield') then
             local receiver = callNode.node
@@ -1571,7 +1673,6 @@ local function bindReturnOfFunction(source, mfunc, index, args)
                     if rn.type == 'doc.type.sign' and rn.signs and rn.node and rn.node[1] then
                         local classGlobal = vm.getGlobal('type', rn.node[1])
                         if classGlobal then
-                            -- Build a map of class generic param names to their concrete types
                             local genericMap = {}
                             for _, set in ipairs(classGlobal:getSets(guide.getUri(source))) do
                                 if set.type == 'doc.class' and set.signs then
@@ -1616,7 +1717,6 @@ local function bindReturnOfFunction(source, mfunc, index, args)
 
     if returnNode then
         for rnode in returnNode:eachObject() do
-            -- TODO: narrow type
             if rnode.type ~= 'doc.generic.name' then
                 vm.setNode(source, rnode)
             end
@@ -2191,7 +2291,11 @@ local compilerSwitch = util.switch()
     end)
     : case 'doc.generic.name'
     : call(function (source)
-        vm.setNode(source, source)
+        if source._resolved then
+            vm.setNode(source, source._resolved)
+        else
+            vm.setNode(source, source)
+        end
     end)
     : case 'doc.type.sign'
     : call(function (source)

test/type_inference/common.lua

@@ -5046,3 +5046,126 @@ local f
 
 local <?wrapped?> = f:wrap()
 ]]
+
+-- Issue #723: Generics in @overload
+-- @generic should work with @overload annotations
+TEST 'string' [[
+---@generic T
+---@param x T
+---@return T
+---@overload fun(x: T): T
+local function identity(x)
+    return x
+end
+
+local <?result?> = identity("hello")
+]]
+
+-- Issue #723: Multiple generics in @overload
+TEST 'integer' [[
+---@generic K, V
+---@param k K
+---@param v V
+---@return V
+---@overload fun(k: K, v: V): V
+local function getValue(k, v)
+    return v
+end
+
+local <?result?> = getValue("key", 42)
+]]
+
+-- Issue #1170: Generics in function type format (fun<T>)
+TEST 'string' [[
+---@type fun<T>(x: T): T
+local identity
+
+local <?result?> = identity("hello")
+]]
+
+-- Issue #1170: Multiple generics in function type
+TEST 'boolean' [[
+---@type fun<K, V>(k: K, v: V): V
+local getSecond
+
+local <?result?> = getSecond("key", true)
+]]
+
+-- Issue #1170: Generic function in @field
+TEST 'integer' [[
+---@class Mapper
+---@field transform fun<T, U>(input: T, fn: fun(x: T): U): U
+
+---@type Mapper
+local m
+
+local <?result?> = m.transform("hello", function(x) return #x end)
+]]
+
+-- Issue #1532: Promise-like method chaining
+-- Method returning self-type should preserve generic param through chain
+TEST 'string' [[
+---@class Promise<T>
+---@field value T
+local Promise = {}
+
+---@return Promise<T>
+function Promise:next(fn)
+    return self
+end
+
+---@return T
+function Promise:await()
+    return self.value
+end
+
+---@type Promise<string>
+local p
+
+local <?result?> = p:next(function() end):await()
+]]
+
+-- Issue #1532: Multiple chained methods
+TEST 'number' [[
+---@class Chain<V>
+local Chain = {}
+
+---@return Chain<V>
+function Chain:map(fn)
+    return self
+end
+
+---@return Chain<V>
+function Chain:filter(fn)
+    return self
+end
+
+---@return V
+function Chain:first()
+    return nil
+end
+
+---@type Chain<number>
+local c
+
+local <?result?> = c:map(function() end):filter(function() end):first()
+]]
+
+-- Issue #1000: Generic self parameter should resolve to concrete type
+-- When @generic T and @param self T, calling on List<number> should return List<number>
+TEST 'List<number>' [[
+---@class List<V>
+local List = {}
+
+---@generic T
+---@param self T
+---@return T
+function List:identity()
+    return self
+end
+
+---@type List<number>
+local mylist
+
+local <?result?> = mylist:identity()
+]]