Merge pull request #2107 from AlWoSp/thwe/missing-local-export-doc

Annotation rule for exported local functions

4 files changed, 130 insertions, 73 deletions

diff --git a/script/core/diagnostics/helper/missing-doc-helper.lua b/script/core/diagnostics/helper/missing-doc-helper.lua
new file mode 100644
index 00000000..84221693
--- /dev/null
+++ b/script/core/diagnostics/helper/missing-doc-helper.lua
@@ -0,0 +1,81 @@
+local lang    = require 'language'
+
+local m = {}
+
+local function findParam(docs, param)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.param' then
+            if doc.param[1] == param then
+                return true
+            end
+        end
+    end
+
+    return false
+end
+
+local function findReturn(docs, index)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.return' then
+            for _, ret in ipairs(doc.returns) do
+                if ret.returnIndex == index then
+                    return true
+                end
+            end
+        end
+    end
+
+    return false
+end
+
+local function checkFunction(source, callback, commentId, paramId, returnId)
+    local functionName = source.parent[1]
+
+    if #source.args == 0 and not source.returns and not source.bindDocs then
+        callback {
+            start   = source.start,
+            finish  = source.finish,
+            message = lang.script(commentId, functionName),
+        }
+    end
+
+    if #source.args > 0 then
+        for _, arg in ipairs(source.args) do
+            local argName = arg[1]
+            if argName ~= 'self' then
+                if not findParam(source.bindDocs, argName) then
+                    callback {
+                        start   = arg.start,
+                        finish  = arg.finish,
+                        message = lang.script(paramId, argName, functionName),
+                    }
+                end
+            end
+        end
+    end
+
+    if source.returns then
+        for _, ret in ipairs(source.returns) do
+            for index, expr in ipairs(ret) do
+                if not findReturn(source.bindDocs, index) then
+                    callback {
+                        start   = expr.start,
+                        finish  = expr.finish,
+                        message = lang.script(returnId, index, functionName),
+                    }
+                end
+            end
+        end
+    end
+end
+
+m.CheckFunction = checkFunction
+return m
diff --git a/script/core/diagnostics/missing-global-doc.lua b/script/core/diagnostics/missing-global-doc.lua
index adcdf404..e104d232 100644
--- a/script/core/diagnostics/missing-global-doc.lua
+++ b/script/core/diagnostics/missing-global-doc.lua
@@ -1,41 +1,7 @@
 local files   = require 'files'
-local lang    = require 'language'
 local guide   = require "parser.guide"
 local await   = require 'await'
-
-local function findParam(docs, param)
-    if not docs then
-        return false
-    end
-
-    for _, doc in ipairs(docs) do
-        if doc.type == 'doc.param' then
-            if doc.param[1] == param then
-                return true
-            end
-        end
-    end
-
-    return false
-end
-
-local function findReturn(docs, index)
-    if not docs then
-        return false
-    end
-
-    for _, doc in ipairs(docs) do
-        if doc.type == 'doc.return' then
-            for _, ret in ipairs(doc.returns) do
-                if ret.returnIndex == index then
-                    return true
-                end
-            end
-        end
-    end
-
-    return false
-end
+local helper  = require 'core.diagnostics.helper.missing-doc-helper'
 
 ---@async
 return function (uri, callback)
@@ -56,43 +22,6 @@ return function (uri, callback)
             return
         end
 
-        local functionName = source.parent[1]
-
-        if #source.args == 0 and not source.returns and not source.bindDocs then
-            callback {
-                start   = source.start,
-                finish  = source.finish,
-                message = lang.script('DIAG_MISSING_GLOBAL_DOC_COMMENT', functionName),
-            }
-        end
-
-        if #source.args > 0 then
-            for _, arg in ipairs(source.args) do
-                local argName = arg[1]
-                if argName ~= 'self' then
-                    if not findParam(source.bindDocs, argName) then
-                        callback {
-                            start   = arg.start,
-                            finish  = arg.finish,
-                            message = lang.script('DIAG_MISSING_GLOBAL_DOC_PARAM', argName, functionName),
-                        }
-                    end
-                end
-            end
-        end
-
-        if  source.returns then
-            for _, ret in ipairs(source.returns) do
-                for index, expr in ipairs(ret) do
-                    if not findReturn(source.bindDocs, index) then
-                        callback {
-                            start   = expr.start,
-                            finish  = expr.finish,
-                            message = lang.script('DIAG_MISSING_GLOBAL_DOC_RETURN', index, functionName),
-                        }
-                    end
-                end
-            end
-        end
+        helper.CheckFunction(source, callback, 'DIAG_MISSING_GLOBAL_DOC_COMMENT', 'DIAG_MISSING_GLOBAL_DOC_PARAM', 'DIAG_MISSING_GLOBAL_DOC_RETURN')
     end)
 end
diff --git a/script/core/diagnostics/missing-local-export-doc.lua b/script/core/diagnostics/missing-local-export-doc.lua
new file mode 100644
index 00000000..5825c115
--- /dev/null
+++ b/script/core/diagnostics/missing-local-export-doc.lua
@@ -0,0 +1,46 @@
+local files   = require 'files'
+local guide   = require "parser.guide"
+local await   = require 'await'
+local helper  = require 'core.diagnostics.helper.missing-doc-helper'
+
+---@async
+local function findSetField(ast, name, callback)
+    ---@async
+    guide.eachSourceType(ast, 'setfield', function (source)
+        await.delay()
+        if source.node[1] == name then
+            local funcPtr = source.value.node
+            local func = funcPtr.value
+            if funcPtr.type == 'local' and func.type == 'function' then
+                helper.CheckFunction(func, callback, 'DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT', 'DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM', 'DIAG_MISSING_LOCAL_EXPORT_DOC_RETURN')
+            end
+        end
+    end)
+end
+
+---@async
+return function (uri, callback)
+    local state = files.getState(uri)
+
+    if not state then
+        return
+    end
+
+    if not state.ast then
+        return
+    end
+
+    ---@async
+    guide.eachSourceType(state.ast, 'return', function (source)
+        await.delay()
+        --table
+
+        for i, ret in ipairs(source) do
+            if ret.type == 'getlocal' then
+                if ret.node.value and ret.node.value.type == 'table' then
+                    findSetField(state.ast, ret[1], callback)
+                end
+            end
+        end
+    end)
+end
diff --git a/script/proto/diagnostic.lua b/script/proto/diagnostic.lua
index bd10b7f7..8175a2c5 100644
--- a/script/proto/diagnostic.lua
+++ b/script/proto/diagnostic.lua
@@ -103,6 +103,7 @@ m.register {
 m.register {
     'incomplete-signature-doc',
     'missing-global-doc',
+    'missing-local-export-doc',
 } {
     group    = 'luadoc',
     severity = 'Warning',