From d2a08abb38a413dddd19edb69971d2b0657bff6f Mon Sep 17 00:00:00 2001 From: Thomas Wetzlmaier Date: Thu, 11 May 2023 16:32:53 +0200 Subject: Annotation rule for exported local functions Annotation for the following local function func1 is required. local mod = { } local function func1() end mod.Func1 = func1 return mod; --- .../core/diagnostics/helper/missing-doc-helper.lua | 81 ++++++++++++++++++++++ script/core/diagnostics/missing-global-doc.lua | 75 +------------------- .../core/diagnostics/missing-local-export-doc.lua | 46 ++++++++++++ script/proto/diagnostic.lua | 1 + 4 files changed, 130 insertions(+), 73 deletions(-) create mode 100644 script/core/diagnostics/helper/missing-doc-helper.lua create mode 100644 script/core/diagnostics/missing-local-export-doc.lua (limited to 'script') 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', -- cgit v1.2.3