Support limited multiline annotations

Author: sumneko

changelog.md

@@ -3,7 +3,16 @@
 ## Unreleased
 <!-- Add all new changes here. They will be moved under a version at release -->
 * `FIX` A regression related to type narrow and generic param introduced since `v3.10.1`
-* `New` Support importing `enum` through class name suffix matching in quick fixes, allowing the import of `enum` from `table.table.enum; return table`.
+* `NEW` Support importing `enum` through class name suffix matching in quick fixes, allowing the import of `enum` from `table.table.enum; return table`.
+* `NEW` Support limited multiline annotations
+  ```lua
+  ---@type {
+  --- x: number,
+  --- y: number,
+  --- z: number,
+  ---}
+  local point --> local point: { x: number, y: number, z: number }
+  ```
 * `FIX` Parse storagePath to improve reliability of resolving ${addons} placeholder
 * `FIX` Reference should also look in tablefield
 * `FIX` Determine that the index of `{...}` is an integer when iterating

script/parser/luadoc.lua

@@ -298,6 +298,30 @@ local function parseIndexField(parent)
     return field
 end
 
+local function slideToNextLine()
+    if peekToken() then
+        return
+    end
+    local nextComment = NextComment(0, true)
+    if not nextComment then
+        return
+    end
+    local currentComment = NextComment(-1, true)
+    local currentLine = guide.rowColOf(currentComment.start)
+    local nextLine = guide.rowColOf(nextComment.start)
+    if currentLine + 1 ~= nextLine then
+        return
+    end
+    if nextComment.text:sub(1, 1) ~= '-' then
+        return
+    end
+    if nextComment.text:match '^%-%s*%@' then
+        return
+    end
+    NextComment()
+    parseTokens(nextComment.text:sub(2), nextComment.start + 2)
+end
+
 local function parseTable(parent)
     if not checkToken('symbol', '{', 1) then
         return nil
@@ -311,6 +335,7 @@ local function parseTable(parent)
     }
 
     while true do
+        slideToNextLine()
         if checkToken('symbol', '}', 1) then
             nextToken()
             break
@@ -385,6 +410,7 @@ local function parseTuple(parent)
 
     local index = 1
     while true do
+        slideToNextLine()
         if checkToken('symbol', ']', 1) then
             nextToken()
             break
@@ -500,6 +526,7 @@ local function  parseTypeUnitFunction(parent)
         return nil
     end
     while true do
+        slideToNextLine()
         if checkToken('symbol', ')', 1) then
             nextToken()
             break
@@ -539,14 +566,17 @@ local function  parseTypeUnitFunction(parent)
             break
         end
     end
+    slideToNextLine()
     if checkToken('symbol', ':', 1) then
         nextToken()
+        slideToNextLine()
         local needCloseParen
         if checkToken('symbol', '(', 1) then
             nextToken()
             needCloseParen = true
         end
         while true do
+            slideToNextLine()
             local name
             try(function ()
                 local returnName = parseName('doc.return.name', typeUnit)
@@ -2139,10 +2169,10 @@ local function bindDocs(state)
             state.ast.docs.groups[#state.ast.docs.groups+1] = binded
         end
         binded[#binded+1] = doc
-		if doc.specialBindGroup then
-			bindDocWithSources(sources, doc.specialBindGroup)
-			binded = nil
-		elseif isTailComment(text, doc) and doc.type ~= "doc.class" and doc.type ~= "doc.field" then
+        if doc.specialBindGroup then
+            bindDocWithSources(sources, doc.specialBindGroup)
+            binded = nil
+        elseif isTailComment(text, doc) and doc.type ~= "doc.class" and doc.type ~= "doc.field" then
             bindDocWithSources(sources, binded)
             binded = nil
         else
@@ -2278,7 +2308,7 @@ return {
             doc.special = src
             doc.originalComment = comment
             doc.virtual = true
-			doc.specialBindGroup = group
+            doc.specialBindGroup = group
             ast.state.pluginDocs = pluginDocs
             return doc
         end