Merge branch '1.21.0'

9 files changed, 211 insertions, 157 deletions

diff --git a/changelog.md b/changelog.md
index 371d77cd..4f7ac9c2 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,10 @@
 # changelog
 
+## 1.21.0
+* `NEW` setting: `completion.showParams`
+* `NEW` `LuaDoc`: supports multiline comments
+* `NEW` `LuaDoc`: tail comments support lua string
+
 ## 1.20.5
 `2021-4-30`
 * `NEW` setting: `completion.autoRequire`
diff --git a/script/config.lua b/script/config.lua
index 8bc05b98..97df7c17 100644
--- a/script/config.lua
+++ b/script/config.lua
@@ -165,6 +165,7 @@ local ConfigTemplate = {
         displayContext  = {6,         Integer},
         workspaceWord   = {true,      Boolean},
         autoRequire     = {true,      Boolean},
+        showParams      = {true,      Boolean},
     },
     signatureHelp = {
         enable          = {true,      Boolean},
diff --git a/script/core/completion.lua b/script/core/completion.lua
index 98a9250f..ee61029d 100644
--- a/script/core/completion.lua
+++ b/script/core/completion.lua
@@ -121,17 +121,9 @@ local function findParentInStringIndex(ast, text, offset)
     return parent.node, false
 end
 
-local function buildFunctionSnip(source, oop)
+local function buildFunctionSnip(source, value, oop)
     local name = getName(source):gsub('^.+[$.:]', '')
-    local defs = vm.getDefs(source, 0)
-    local args = ''
-    for _, def in ipairs(defs) do
-        local defArgs = getArg(def, oop)
-        if defArgs ~= '' then
-            args = defArgs
-            break
-        end
-    end
+    local args = getArg(value, oop)
     local id = 0
     args = args:gsub('[^,]+', function (arg)
         id = id + 1
@@ -191,7 +183,7 @@ local function buildDesc(source)
     return md:string()
 end
 
-local function buildFunction(results, source, oop, data)
+local function buildFunction(results, source, value, oop, data)
     local snipType = config.config.completion.callSnippet
     if snipType == 'Disable' or snipType == 'Both' then
         results[#results+1] = data
@@ -199,8 +191,7 @@ local function buildFunction(results, source, oop, data)
     if snipType == 'Both' or snipType == 'Replace' then
         local snipData = util.deepCopy(data)
         snipData.kind = define.CompletionItemKind.Snippet
-        snipData.label = snipData.label .. '()'
-        snipData.insertText = buildFunctionSnip(source, oop)
+        snipData.insertText = buildFunctionSnip(source, value, oop)
         snipData.insertTextFormat = 2
         snipData.id  = stack(function ()
             return {
@@ -253,6 +244,26 @@ local function isSameSource(ast, source, pos)
     return source.start <= pos and source.finish >= pos
 end
 
+local function getParams(func, oop)
+    if not func.args then
+        return '()'
+    end
+    local args = {}
+    for _, arg in ipairs(func.args) do
+        if arg.type == '...' then
+            args[#args+1] = '...'
+        elseif arg.type == 'doc.type.arg' then
+            args[#args+1] = arg.name[1]
+        else
+            args[#args+1] = arg[1]
+        end
+    end
+    if oop and args[1] ~= '...' then
+        table.remove(args, 1)
+    end
+    return '(' .. table.concat(args, ', ') .. ')'
+end
+
 local function checkLocal(ast, word, offset, results)
     local locals = guide.getVisibleLocals(ast.ast, offset)
     for name, source in pairs(locals) do
@@ -263,16 +274,23 @@ local function checkLocal(ast, word, offset, results)
             goto CONTINUE
         end
         if vm.hasType(source, 'function') then
-            buildFunction(results, source, false, {
-                label  = name,
-                kind   = define.CompletionItemKind.Function,
-                id     = stack(function ()
-                    return {
-                        detail      = buildDetail(source),
-                        description = buildDesc(source),
-                    }
-                end),
-            })
+            for _, def in ipairs(vm.getDefs(source, 0)) do
+                if def.type == 'function'
+                or def.type == 'doc.type.function' then
+                    local funcLabel = name .. getParams(def, false)
+                    buildFunction(results, source, def, false, {
+                        label  = funcLabel,
+                        insertText = name,
+                        kind   = define.CompletionItemKind.Function,
+                        id     = stack(function ()
+                            return {
+                                detail      = buildDetail(source),
+                                description = buildDesc(source),
+                            }
+                        end),
+                    })
+                end
+            end
         else
             results[#results+1] = {
                 label  = name,
@@ -401,15 +419,17 @@ end
 local function checkFieldThen(name, src, word, start, offset, parent, oop, results)
     local value = guide.getObjectValue(src) or src
     local kind = define.CompletionItemKind.Field
-    if value.type == 'function' then
+    if value.type == 'function'
+    or value.type == 'doc.type.function' then
         if oop then
             kind = define.CompletionItemKind.Method
         else
             kind = define.CompletionItemKind.Function
         end
-        buildFunction(results, src, oop, {
+        buildFunction(results, src, value, oop, {
             label      = name,
             kind       = kind,
+            insertText = name:match '^[^(]+',
             deprecated = vm.isDeprecated(src) or nil,
             id         = stack(function ()
                 return {
@@ -470,8 +490,28 @@ local function checkFieldOfRefs(refs, ast, word, start, offset, parent, oop, res
         if not matchKey(word, name, count >= 100) then
             goto CONTINUE
         end
+        local funcLabel
+        if config.config.completion.showParams then
+            local value = guide.getObjectValue(src) or src
+            if value.type == 'function'
+            or value.type == 'doc.type.function' then
+                funcLabel = name .. getParams(value, oop)
+                fields[funcLabel] = src
+                fields[name] = false
+                count = count + 1
+                if value.type == 'function' and value.bindDocs then
+                    for _, doc in ipairs(value.bindDocs) do
+                        if doc.type == 'doc.overload' then
+                            funcLabel = name .. getParams(doc.overload, oop)
+                            fields[funcLabel] = doc.overload
+                        end
+                    end
+                end
+                goto CONTINUE
+            end
+        end
         local last = fields[name]
-        if not last then
+        if last == nil then
             fields[name] = src
             count = count + 1
             goto CONTINUE
@@ -491,7 +531,9 @@ local function checkFieldOfRefs(refs, ast, word, start, offset, parent, oop, res
         ::CONTINUE::
     end
     for name, src in util.sortPairs(fields) do
-        checkFieldThen(name, src, word, start, offset, parent, oop, results)
+        if src then
+            checkFieldThen(name, src, word, start, offset, parent, oop, results)
+        end
     end
 end
 
@@ -544,7 +586,7 @@ local function checkCommon(myUri, word, text, offset, results)
     results.enableCommon = true
     local used = {}
     for _, result in ipairs(results) do
-        used[result.label] = true
+        used[result.label:match '^[^(]*'] = true
     end
     for _, data in ipairs(keyWordMap) do
         used[data[1]] = true
diff --git a/script/core/guide.lua b/script/core/guide.lua
index 367b91e2..e4871060 100644
--- a/script/core/guide.lua
+++ b/script/core/guide.lua
@@ -1842,6 +1842,8 @@ function m.checkSameSimpleByBindDocs(status, obj, start, pushQueue, mode)
             if obj.type == '...' then
                 results[#results+1] = doc
             end
+        elseif doc.type == 'doc.overload' then
+            results[#results+1] = doc.overload
         end
     end
     for _, res in ipairs(results) do
diff --git a/script/parser/ast.lua b/script/parser/ast.lua
index 38c4e51b..3ac4d27f 100644
--- a/script/parser/ast.lua
+++ b/script/parser/ast.lua
@@ -277,7 +277,7 @@ local Defs = {
             type   = 'comment.long',
             start  = start,
             finish = finish - 1,
-            text   = '',
+            text   = str,
         }
         if not close then
             local endSymbol = ']' .. ('='):rep(afterEq-beforeEq) .. ']'
@@ -318,7 +318,7 @@ local Defs = {
             }
         end
     end,
-    CLongComment = function (start1, finish1, start2, finish2)
+    CLongComment = function (start1, finish1, str, start2, finish2)
         if State.options.nonstandardSymbol and State.options.nonstandardSymbol['/**/'] then
         else
             PushError {
@@ -344,7 +344,7 @@ local Defs = {
             type     = 'comment.clong',
             start    = start1,
             finish   = finish2 - 1,
-            text     = '',
+            text     = str,
         }
     end,
     CCommentPrefix = function (start, finish, commentFinish)
diff --git a/script/parser/grammar.lua b/script/parser/grammar.lua
index ea9a25e0..01756c2a 100644
--- a/script/parser/grammar.lua
+++ b/script/parser/grammar.lua
@@ -88,13 +88,13 @@ end
 grammar 'Comment' [[
 Comment         <-  LongComment
                 /   '--' ShortComment
-LongComment     <-  ({} '--[' {} {:eq: '='* :} {} '[' 
+LongComment     <-  ({} '--[' {} {:eq: '='* :} {} '[' %nl?
                     {(!CommentClose .)*}
                     ((CommentClose / %nil) {}))
                 ->  LongComment
                 /   (
-                    {} '/*' {}
-                    (!'*/' .)*
+                    {} '/*' {} %nl?
+                    {(!'*/' .)*}
                     {} '*/' {}
                     )
                 ->  CLongComment
diff --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua
index 74e53718..3ab9f6a1 100644
--- a/script/parser/luadoc.lua
+++ b/script/parser/luadoc.lua
@@ -2,6 +2,7 @@ local m          = require 'lpeglabel'
 local re         = require 'parser.relabel'
 local lines      = require 'parser.lines'
 local guide      = require 'core.guide'
+local grammar    = require 'parser.grammar'
 
 local TokenTypes, TokenStarts, TokenFinishs, TokenContents
 local Ci, Offset, pushError, Ct, NextComment, Lines
@@ -999,16 +1000,23 @@ local function convertTokens()
 end
 
 local function trimTailComment(text)
+    local comment = text
     if text:sub(1, 1) == '@' then
-        return text:sub(2)
+        comment = text:sub(2)
     end
     if text:sub(1, 1) == '#' then
-        return text:sub(2)
+        comment = text:sub(2)
     end
     if text:sub(1, 2) == '--' then
-        return text:sub(3)
+        comment = text:sub(3)
     end
-    return text
+    if comment:find '^%s*[\'"[]' then
+        local result = grammar(nil, comment:gsub('^%s+', ''), 'string')
+        if result then
+            comment = result[1][1]
+        end
+    end
+    return comment
 end
 
 local function buildLuaDoc(comment)
@@ -1185,7 +1193,7 @@ local function bindDoc(sources, lns, binded)
     end
     bindGeneric(binded)
     local row = guide.positionOf(lns, lastDoc.finish)
-    local cstart, cfinish  = guide.lineRange(lns, row)
+    local cstart, cfinish = guide.lineRange(lns, row)
     local nstart, nfinish = guide.lineRange(lns, row + 1)
     bindDocsBetween(sources, binded, bindSources, cstart, cfinish)
     if #bindSources == 0 then
diff --git a/test/completion/init.lua b/test/completion/init.lua
index 22103896..89772853 100644
--- a/test/completion/init.lua
+++ b/test/completion/init.lua
@@ -60,6 +60,8 @@ local Cared = {
     ['deprecated']          = true,
 }
 
+local IgnoreFunction = false
+
 function TEST(script)
     return function (expect)
         files.removeAll()
@@ -86,6 +88,16 @@ function TEST(script)
                 end
             end
         end
+        if IgnoreFunction then
+            for i = #result, 1, -1 do
+                local item = result[i]
+                if item.label:find '%('
+                and not item.label:find 'function' then
+                    result[i] = result[#result]
+                    result[#result] = nil
+                end
+            end
+        end
         assert(result)
         if expect.include then
             expect.include = nil
@@ -175,11 +187,11 @@ ass$
 ]]
 {
     {
-        label = 'assert',
+        label = 'assert(v, message)',
         kind  = define.CompletionItemKind.Function,
     },
     {
-        label = 'assert()',
+        label = 'assert(v, message)',
         kind  = define.CompletionItemKind.Snippet,
     },
 }
@@ -201,11 +213,11 @@ _G.ass$
 ]]
 {
     {
-        label = 'assert',
+        label = 'assert(v, message)',
         kind  = define.CompletionItemKind.Function,
     },
     {
-        label = 'assert()',
+        label = 'assert(v, message)',
         kind  = define.CompletionItemKind.Snippet,
     },
 }
@@ -217,11 +229,11 @@ ff$
 ]]
 {
     {
-        label = 'ffff',
+        label = 'ffff(a, b)',
         kind  = define.CompletionItemKind.Function,
     },
     {
-        label = 'ffff()',
+        label = 'ffff(a, b)',
         kind  = define.CompletionItemKind.Snippet,
     }
 }
@@ -285,11 +297,11 @@ mt:g$
 ]]
 {
     {
-        label = 'get',
+        label = 'get(a, b)',
         kind = define.CompletionItemKind.Method,
     },
     {
-        label = 'get()',
+        label = 'get(a, b)',
         kind = define.CompletionItemKind.Snippet,
     },
     {
@@ -311,15 +323,16 @@ loc$
         kind = define.CompletionItemKind.Snippet,
     },
     {
-        label = 'collectgarbage',
+        label = 'collectgarbage(opt, ...)',
         kind = define.CompletionItemKind.Function,
     },
     {
-        label = 'collectgarbage()',
+        label = 'collectgarbage(opt, ...)',
         kind = define.CompletionItemKind.Snippet,
     },
 }
 
+IgnoreFunction = true
 TEST [[
 do$
 ]]
@@ -332,50 +345,6 @@ do$
         label = 'do .. end',
         kind = define.CompletionItemKind.Snippet,
     },
-    {
-        label = 'dofile',
-        kind  = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'dofile()',
-        kind  = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'load',
-        kind  = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'load()',
-        kind  = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'loadfile',
-        kind  = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'loadfile()',
-        kind  = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'loadstring',
-        kind  = define.CompletionItemKind.Function,
-        deprecated = true,
-    },
-    {
-        label = 'loadstring()',
-        kind  = define.CompletionItemKind.Snippet,
-        deprecated = true,
-    },
-    {
-        label = 'module',
-        kind  = define.CompletionItemKind.Function,
-        deprecated = true,
-    },
-    {
-        label = 'module()',
-        kind  = define.CompletionItemKind.Snippet,
-        deprecated = true,
-    },
 }
 
 TEST [[
@@ -454,6 +423,7 @@ t.   $
     },
 }
 
+IgnoreFunction = false
 TEST [[
 t.a = {}
 function t:b()
@@ -462,7 +432,7 @@ t:$
 ]]
 {
     {
-        label = 'b',
+        label = 'b()',
         kind = define.CompletionItemKind.Method,
     },
     {
@@ -507,6 +477,7 @@ TEST 'local s = "a:$"' (nil)
 TEST 'debug.$'
 (EXISTS)
 
+IgnoreFunction = true
 TEST [[
 local xxxx = {
     xxyy = 1,
@@ -530,22 +501,6 @@ local t = {
         label = 'xxzz',
         kind = define.CompletionItemKind.Property,
     },
-    {
-        label = 'next',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'next()',
-        kind = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'xpcall',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'xpcall()',
-        kind = define.CompletionItemKind.Snippet,
-    },
 }
 
 TEST [[
@@ -1030,25 +985,10 @@ else$
         label = 'ELSE',
         kind = define.CompletionItemKind.Enum,
     },
-    {
-        label = 'select',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'select()',
-        kind = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'setmetatable',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'setmetatable()',
-        kind = define.CompletionItemKind.Snippet,
-    },
 }
 
 Cared['insertText'] = true
+IgnoreFunction = false
 TEST [[
 local xpcal
 xpcal$
@@ -1059,11 +999,12 @@ xpcal$
         kind = define.CompletionItemKind.Variable,
     },
     {
-        label = 'xpcall',
+        label = 'xpcall(f, msgh, arg1, ...)',
         kind = define.CompletionItemKind.Function,
+        insertText = EXISTS,
     },
     {
-        label = 'xpcall()',
+        label = 'xpcall(f, msgh, arg1, ...)',
         kind = define.CompletionItemKind.Snippet,
         insertText = EXISTS,
     },
@@ -1077,11 +1018,12 @@ mt:f$
 ]]
 {
     {
-        label = 'f',
+        label = 'f(a, b, c)',
         kind = define.CompletionItemKind.Method,
+        insertText = EXISTS,
     },
     {
-        label = 'f()',
+        label = 'f(a, b, c)',
         kind = define.CompletionItemKind.Snippet,
         insertText = 'f(${1:a: any}, ${2:b: any}, ${3:c: any})',
     },
@@ -1123,6 +1065,7 @@ end",
     },
 }
 Cared['insertText'] = false
+IgnoreFunction = true
 
 TEST [[
 local function f()
@@ -1143,22 +1086,6 @@ end
         label = 'elseif .. then',
         kind = define.CompletionItemKind.Snippet,
     },
-    {
-        label = 'select',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'select()',
-        kind = define.CompletionItemKind.Snippet,
-    },
-    {
-        label = 'setmetatable',
-        kind = define.CompletionItemKind.Function,
-    },
-    {
-        label = 'setmetatable()',
-        kind = define.CompletionItemKind.Snippet,
-    },
 }
 
 TEST [[
@@ -1259,17 +1186,18 @@ io$
 ]]
 (EXISTS)
 
+IgnoreFunction = false
 TEST [[
 loadstring$
 ]]
 {
     {
-        label = 'loadstring',
+        label = 'loadstring(text, chunkname)',
         kind  = define.CompletionItemKind.Function,
         deprecated = true,
     },
     {
-        label = 'loadstring()',
+        label = 'loadstring(text, chunkname)',
         kind  = define.CompletionItemKind.Snippet,
         deprecated = true,
     },
@@ -1293,13 +1221,23 @@ loadstring$
 ]]
 {
     {
-        label = 'loadstring',
+        label = 'loadstring()',
         kind  = define.CompletionItemKind.Function,
     },
     {
         label = 'loadstring()',
         kind  = define.CompletionItemKind.Snippet,
     },
+    {
+        label = 'loadstring(text, chunkname)',
+        deprecated = true,
+        kind  = define.CompletionItemKind.Function,
+    },
+    {
+        label = 'loadstring(text, chunkname)',
+        deprecated = true,
+        kind  = define.CompletionItemKind.Snippet,
+    },
 }
 
 TEST [[
@@ -1307,12 +1245,12 @@ debug.setcsta$
 ]]
 {
     {
-        label = 'setcstacklimit',
+        label = 'setcstacklimit(limit)',
         kind = define.CompletionItemKind.Function,
         deprecated = true,
     },
     {
-        label = 'setcstacklimit()',
+        label = 'setcstacklimit(limit)',
         kind = define.CompletionItemKind.Snippet,
         deprecated = true,
     },
@@ -1837,9 +1775,6 @@ end)
 
 TEST [[
 --- JustTest
----@overload fun(list:table):string
----@overload fun(list:table, sep:string):string
----@overload fun(list:table, sep:string, i:number):string
 ---@param list table
 ---@param sep string
 ---@param i number
@@ -1851,11 +1786,12 @@ zzz$
 ]]
 {
     {
-        label = 'zzzzz',
+        label = 'zzzzz(list, sep, i, j)',
         kind = define.CompletionItemKind.Function,
+        insertText = EXISTS,
     },
     {
-        label = 'zzzzz()',
+        label = 'zzzzz(list, sep, i, j)',
         kind = define.CompletionItemKind.Snippet,
         insertText = EXISTS,
     }
@@ -2334,8 +2270,9 @@ end
 m.f$
 ]]{
     {
-        label  = "f",
+        label  = "f()",
         kind   = define.CompletionItemKind.Function,
+        insertText = EXISTS,
     },
     {
         label  = "f()",
@@ -2541,3 +2478,32 @@ TEST [[
         },
     }
 }
+
+Cared['insertText'] = true
+TEST [[
+---@overload fun(a: any, b: any)
+local function zzzz(a) end
+zzzz$
+]]
+{
+    {
+        label = 'zzzz(a)',
+        kind  = define.CompletionItemKind.Function,
+        insertText = 'zzzz',
+    },
+    {
+        label = 'zzzz(a)',
+        kind  = define.CompletionItemKind.Snippet,
+        insertText = 'zzzz(${1:a: any})',
+    },
+    {
+        label = 'zzzz(a, b)',
+        kind  = define.CompletionItemKind.Function,
+        insertText = 'zzzz',
+    },
+    {
+        label = 'zzzz(a, b)',
+        kind  = define.CompletionItemKind.Snippet,
+        insertText = 'zzzz(${1:a: any}, ${2:b: any})',
+    },
+}
diff --git a/test/crossfile/hover.lua b/test/crossfile/hover.lua
index 521f5a49..bf56b39a 100644
--- a/test/crossfile/hover.lua
+++ b/test/crossfile/hover.lua
@@ -731,3 +731,33 @@ hover = {
     label = 'field Food.firstField: integer = 0',
     name  = 'food.firstField',
 }}
+
+TEST {{ path = 'a.lua', content = '', }, {
+    path = 'b.lua',
+    content = [[
+--[=[
+I'm a multiline comment
+]=]
+local <?food?>
+]]
+},
+hover = {
+    label = 'local food: any',
+    name  = 'food',
+    description = "I'm a multiline comment\n"
+}}
+
+TEST {{ path = 'a.lua', content = '', }, {
+    path = 'b.lua',
+    content = [[
+---@return string # 'this is a tab `\t`'
+local function <?f?>() end
+]]
+},
+hover = {
+    label = [[
+function f()
+  -> string]],
+    name  = 'food',
+    description = "@*return* — this is a tab `\t`"
+}}