Merge pull request #3028 from TIMONz1535/TIMONz1535-patch-3

LuaDoc. Fixed the start position of the comment first symbol in docs

Author: sumneko

changelog.md

@@ -13,6 +13,7 @@
   ```
 * `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` 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

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

@@ -1713,10 +1713,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,
@@ -1725,42 +1724,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