#687

6 files changed, 85 insertions, 7 deletions

diff --git a/changelog.md b/changelog.md
index 12830ff8..963a236c 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,9 +1,13 @@
 # changelog
 
 ## 2.5.0
-* `NEW` setting `Lua.runtime.pathStrict`
+* `NEW` settings:
+  + `Lua.runtime.pathStrict`: not check subdirectories when using `runtime.path`
+  + `Lua.hint.await`: display `await` when calling a function marked as async
 * `NEW` add supports of `lovr`
 * `NEW` file encoding supports `utf16le` and `utf16be`
+* `NEW` `LuaDoc` annotations:
+  + `---@async`: mark a function as async
 * `CHG` `LuaDoc` supports unicode
 * `CHG` no longer asks to trust plugin in VSCode, because VSCode already provides the workspace trust feature
 * `CHG` skip huge files (>= 10 MB)
diff --git a/script/config/config.lua b/script/config/config.lua
index 8661e0d0..c2eec880 100644
--- a/script/config/config.lua
+++ b/script/config/config.lua
@@ -199,6 +199,7 @@ local Template = {
     ['Lua.hint.paramType']                  = Type.Boolean >> true,
     ['Lua.hint.setType']                    = Type.Boolean >> false,
     ['Lua.hint.paramName']                  = Type.String  >> 'All',
+    ['Lua.hint.await']                      = Type.Boolean >> true,
     ['Lua.window.statusBar']                = Type.Boolean >> true,
     ['Lua.window.progressBar']              = Type.Boolean >> true,
     ['Lua.telemetry.enable']                = Type.Or(Type.Boolean >> false, Type.Nil),
diff --git a/script/core/completion.lua b/script/core/completion.lua
index d1224934..afa54221 100644
--- a/script/core/completion.lua
+++ b/script/core/completion.lua
@@ -1621,6 +1621,7 @@ local function tryLuaDocCate(word, results)
         'see',
         'diagnostic',
         'module',
+        'async',
     } do
         if matchKey(word, docType) then
             results[#results+1] = {
diff --git a/script/core/hint.lua b/script/core/hint.lua
index 62d2f7bf..11559785 100644
--- a/script/core/hint.lua
+++ b/script/core/hint.lua
@@ -7,12 +7,12 @@ local await    = require 'await'
 local define   = require 'proto.define'
 
 local function typeHint(uri, results, start, finish)
-    local ast = files.getState(uri)
-    if not ast then
+    local state = files.getState(uri)
+    if not state then
         return
     end
     local mark = {}
-    guide.eachSourceBetween(ast.ast, start, finish, function (source)
+    guide.eachSourceBetween(state.ast, start, finish, function (source)
         if  source.type ~= 'local'
         and source.type ~= 'setglobal'
         and source.type ~= 'tablefield'
@@ -101,12 +101,12 @@ local function paramName(uri, results, start, finish)
     if not paramConfig or paramConfig == 'None' then
         return
     end
-    local ast = files.getState(uri)
-    if not ast then
+    local state = files.getState(uri)
+    if not state then
         return
     end
     local mark = {}
-    guide.eachSourceBetween(ast.ast, start, finish, function (source)
+    guide.eachSourceBetween(state.ast, start, finish, function (source)
         if source.type ~= 'call' then
             return
         end
@@ -158,9 +158,37 @@ local function paramName(uri, results, start, finish)
     end)
 end
 
+local function awaitHint(uri, results, start, finish)
+    local awaitConfig = config.get 'Lua.hint.await'
+    if not awaitConfig then
+        return
+    end
+    local state = files.getState(uri)
+    if not state then
+        return
+    end
+    guide.eachSourceBetween(state.ast, start, finish, function (source)
+        if source.type ~= 'call' then
+            return
+        end
+        await.delay()
+        local node = source.node
+        if not vm.isAsync(node, true) then
+            return
+        end
+        results[#results+1] = {
+            text   = 'await ',
+            offset = node.start,
+            kind   = define.InlayHintKind.Other,
+            where  = 'left',
+        }
+    end)
+end
+
 return function (uri, start, finish)
     local results = {}
     typeHint(uri, results, start, finish)
     paramName(uri, results, start, finish)
+    awaitHint(uri, results, start, finish)
     return results
 end
diff --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua
index 2682e2d4..9f286ed4 100644
--- a/script/parser/luadoc.lua
+++ b/script/parser/luadoc.lua
@@ -1098,6 +1098,14 @@ local function parseModule()
     return result
 end
 
+local function parseAsync()
+    return {
+        type   = 'doc.async',
+        start  = getFinish(),
+        finish = getFinish(),
+    }
+end
+
 local function convertTokens()
     local tp, text = nextToken()
     if not tp then
@@ -1141,6 +1149,8 @@ local function convertTokens()
         return parseDiagnostic()
     elseif text == 'module' then
         return parseModule()
+    elseif text == 'async' then
+        return parseAsync()
     end
 end
 
diff --git a/script/vm/getDocs.lua b/script/vm/getDocs.lua
index 2fb2bda9..260d2281 100644
--- a/script/vm/getDocs.lua
+++ b/script/vm/getDocs.lua
@@ -163,6 +163,23 @@ local function isDeprecated(value)
     return false
 end
 
+local function isAsync(value)
+    if not value.bindDocs then
+        return false
+    end
+    if value._async ~= nil then
+        return value._async
+    end
+    for _, doc in ipairs(value.bindDocs) do
+        if doc.type == 'doc.async' then
+            value._async = true
+            return true
+        end
+    end
+    value._async = false
+    return false
+end
+
 function vm.isDeprecated(value, deep)
     if deep then
         local defs = vm.getDefs(value)
@@ -180,6 +197,23 @@ function vm.isDeprecated(value, deep)
     end
 end
 
+function vm.isAsync(value, deep)
+    if deep then
+        local defs = vm.getDefs(value)
+        if #defs == 0 then
+            return false
+        end
+        for _, def in ipairs(defs) do
+            if not isAsync(def) then
+                return false
+            end
+        end
+        return true
+    else
+        return isAsync(value)
+    end
+end
+
 local function makeDiagRange(uri, doc, results)
     local names
     if doc.names then