Merge branch 'master' into TIMONz1535-patch-4

Author: sumneko

changelog.md

@@ -14,6 +14,21 @@
 * `NEW` Test CLI: `--name=<testname>` `-n=<testname>`: run specify unit test
 * `FIX` Fixed the error that the configuration file pointed to by the `--configpath` option was not read and loaded.
 * `FIX` Generic return can be optional.
+* `FIX` Fixed the comment calculating in docs `---@param a string?Comment` - now its `Comment` instead of `omment`.
+* `NEW` `---@class` supports attribute `partial`, which will not check missing inherited fields [#3023](https://github.com/LuaLS/lua-language-server/issues/3023)
+  ```lua
+  ---@class Config
+  ---@field a number
+
+  ---@class (partial) Config.P: Config
+  ---@field b number
+
+  ---@type Config.P[]
+  local cfgs = {}
+  cfgs[1] = { b = 1 } -- no warning
+  cfgs[2] = {}        -- only warns missing `b`
+  ```
+  This enables the previous missing field check behavior before [#2970](https://github.com/LuaLS/lua-language-server/issues/2970)
 
 ## 3.13.5
 `2024-12-20`

script/cli/doc/export.lua

@@ -59,7 +59,7 @@ function export.getLocalPath(uri)
     local local_file_uri = uri
     local i, j = local_file_uri:find(DOC)
     if not j then
-        return '[FORIEGN]'..uri
+        return '[FOREIGN] '..uri
     end
     return local_file_uri:sub( j + 1 )
 end

script/core/completion/completion.lua

@@ -1351,6 +1351,7 @@ local function insertEnum(state, pos, src, enums, isInArray, mark)
             description = description,
             kind        = define.CompletionItemKind.Function,
             insertText  = insertText,
+            insertTextFormat = 2,
         }
     elseif src.type == 'doc.enum' then
         ---@cast src parser.object

script/core/diagnostics/missing-fields.lua

@@ -26,6 +26,18 @@ return function (uri, callback)
                 local className = def.class[1]
                 if not sortedDefs[className] then
                     sortedDefs[className] = {}
+                    -- check if this class is a `partial` class
+                    -- a partial class will not check missing inherited fields
+                    local class = vm.getGlobal('type', className)
+                    ---@cast class -nil
+                    for _, set in ipairs(class:getSets(uri)) do
+                        if set.type == 'doc.class'
+                        and vm.docHasAttr(set, 'partial')
+                        then
+                            sortedDefs[className].isPartial = true
+                            break
+                        end
+                    end
                 end
                 local samedefs = sortedDefs[className]
                 samedefs[#samedefs+1] = def
@@ -41,8 +53,8 @@ return function (uri, callback)
         for className, samedefs in pairs(sortedDefs) do
             local missedKeys = {}
             for _, def in ipairs(samedefs) do
-                local fields = vm.getFields(def)
-                if #fields == 0 then
+                local fields = samedefs.isPartial and def.fields or vm.getFields(def)
+                if not fields or #fields == 0 then
                     goto continue
                 end
 
@@ -78,6 +90,12 @@ return function (uri, callback)
                     end
                 end
                 ::continue::
+
+                if not samedefs.isPartial then
+                    -- if not partial class, then all fields in this class have already been checked
+                    -- because in the above uses `vm.getFields` to get all fields
+                    break
+                end
             end
 
             if #missedKeys == 0 then

script/core/semantic-tokens.lua

@@ -902,23 +902,23 @@ return function (uri, start, finish)
             return
         end
         if start <= comm.start and comm.finish <= finish then
+            -- the same logic as in buildLuaDoc
             local headPos = (comm.type == 'comment.short' and comm.text:match '^%-%s*[@|]()')
-                         or (comm.type == 'comment.long'  and comm.text:match '^@()')
+                         or (comm.type == 'comment.long'  and comm.text:match '^%s*@()')
             if headPos then
-                local atPos
-                if comm.type == 'comment.short' then
-                    atPos = headPos + 2
-                else
-                    atPos = headPos + #comm.mark
+                -- absolute position of `@` symbol
+                local startOffset = comm.start + headPos
+                if comm.type == 'comment.long' then
+                    startOffset = comm.start + headPos + #comm.mark - 2
                 end
                 results[#results+1] = {
                     start  = comm.start,
-                    finish = comm.start + atPos - 2,
+                    finish = startOffset,
                     type   = define.TokenTypes.comment,
                 }
                 results[#results+1] = {
-                    start      = comm.start + atPos - 2,
-                    finish     = comm.start + atPos - 1 + #comm.text:match('%S*', headPos),
+                    start      = startOffset,
+                    finish     = startOffset + #comm.text:match('%S*', headPos) + 1,
                     type       = define.TokenTypes.keyword,
                     modifieres = define.TokenModifiers.documentation,
                 }

script/parser/compile.lua

@@ -590,7 +590,7 @@ local function skipComment(isAction)
         local result, right = resolveLongString '*/'
         pushLongCommentError(left, right)
         State.comms[#State.comms+1] = {
-            type   = 'comment.long',
+            type   = 'comment.clong',
             start  = left,
             finish = right,
             text   = result,

script/parser/luadoc.lua

@@ -1712,10 +1712,9 @@ local function trimTailComment(text)
 end
 
 local function buildLuaDoc(comment)
-    local text = comment.text
-    local startPos = (comment.type == 'comment.short' and text:match '^%-%s*@()')
-                  or (comment.type == 'comment.long'  and text:match '^@()')
-    if not startPos then
+    local headPos = (comment.type == 'comment.short' and comment.text:match '^%-%s*@()')
+                 or (comment.type == 'comment.long'  and comment.text:match '^%s*@()')
+    if not headPos then
         return {
             type    = 'doc.comment',
             start   = comment.start,
@@ -1724,42 +1723,47 @@ local function buildLuaDoc(comment)
             comment = comment,
         }
     end
-    local startOffset = comment.start
+    -- absolute position of `@` symbol
+    local startOffset = comment.start + headPos
     if comment.type == 'comment.long' then
-        startOffset = startOffset + #comment.mark - 2
+        startOffset = comment.start + headPos + #comment.mark - 2
     end
 
-    local doc = text:sub(startPos)
+    local doc = comment.text:sub(headPos)
 
-    parseTokens(doc, startOffset + startPos)
+    parseTokens(doc, startOffset)
     local result, rests = convertTokens(doc)
     if result then
         result.range = math.max(comment.finish, result.finish)
         local finish = result.firstFinish or result.finish
         if rests then
             for _, rest in ipairs(rests) do
-                rest.range = comment.finish
-                finish = rest.firstFinish or result.finish
+                rest.range = math.max(comment.finish, rest.finish)
+                finish = rest.firstFinish or rest.finish
             end
         end
-        local cstart = text:find('%S', finish - comment.start)
-        if cstart and cstart < comment.finish then
+
+        -- `result` can be a multiline annotation or an alias, while `doc` is the first line, so we can't parse comment
+        if finish >= comment.finish then
+            return result, rests
+        end
+
+        local cstart = doc:find('%S', finish - startOffset)
+        if cstart then
             result.comment = {
                 type   = 'doc.tailcomment',
-                start  = cstart + comment.start,
+                start  = startOffset + cstart,
                 finish = comment.finish,
                 parent = result,
-                text   = trimTailComment(text:sub(cstart)),
+                text   = trimTailComment(doc:sub(cstart)),
             }
             if rests then
                 for _, rest in ipairs(rests) do
                     rest.comment = result.comment
                 end
             end
         end
-    end
 
-    if result then
         return result, rests
     end
 

script/vm/sign.lua

@@ -5,7 +5,7 @@ local vm            = require 'vm.vm'
 ---@class vm.sign
 ---@field parent    parser.object
 ---@field signList  vm.node[]
----@field docGenric parser.object[]
+---@field docGeneric parser.object[]
 local mt = {}
 mt.__index = mt
 mt.type = 'sign'
@@ -17,7 +17,7 @@ end
 
 ---@param doc parser.object
 function mt:addDocGeneric(doc)
-    self.docGenric[#self.docGenric+1] = doc
+    self.docGeneric[#self.docGeneric+1] = doc
 end
 
 ---@param uri uri
@@ -268,7 +268,7 @@ end
 function vm.createSign()
     local genericMgr = setmetatable({
         signList  = {},
-        docGenric = {},
+        docGeneric = {},
     }, mt)
     return genericMgr
 end

test/diagnostics/missing-fields.lua

@@ -462,4 +462,38 @@ local function f(b) end
 f <!{y = 1}!>
 ]]
 
+-- partial class
+
+TEST[[
+---@class A
+---@field x number
+
+---@class (partial) B: A
+
+---@type B
+local t = {}
+]]
+
+TEST[[
+---@class A
+---@field x number
+
+---@class (partial) B: A
+---@field y number
+
+---@type B
+local t = <!{}!>
+]]
+
+TEST[[
+---@class A
+---@field x number
+
+---@class (partial) B: A
+---@field y number
+
+---@type B
+local t = {y = 1}
+]]
+
 --