Annotation rule for exported local functions

wetzlmaier · web-flow · commit d2a08abb38a4 · 2023-05-11T16:32:53.000+02:00
Annotation for the following local function func1 is required.

local mod = { }

local function func1()
end

mod.Func1 = func1

return mod;
diff --git a/.luarc.json b/.luarc.json
@@ -3,7 +3,8 @@
         "disable": [
             "close-non-object",
             "incomplete-signature-doc",
-            "missing-global-doc"
+            "missing-global-doc",
+            "missing-local-export-doc"
         ],
         "groupFileStatus": {
             "ambiguity": "Any",
diff --git a/doc/en-us/config.md b/doc/en-us/config.md
@@ -286,6 +286,7 @@ Array<string>
 * ``"miss-space-between"``
 * ``"miss-symbol"``
 * ``"missing-global-doc"``
+* ``"missing-local-export-doc"``
 * ``"missing-parameter"``
 * ``"missing-return"``
 * ``"missing-return-value"``
@@ -453,6 +454,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -578,6 +580,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -814,6 +817,10 @@ object<string, string>
     */
     "missing-global-doc": "None",
     /*
+    Enable diagnostics for exported local function definitions which are not fully annotated.
+    */
+    "missing-local-export-doc": "None",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Any",
@@ -1074,6 +1081,10 @@ object<string, string>
     */
     "missing-global-doc": "Warning",
     /*
+    Enable diagnostics for exported local function definitions which are not annotated.
+    */
+    "missing-local-export-doc": "Warning",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Warning",
diff --git a/doc/pt-br/config.md b/doc/pt-br/config.md
@@ -286,6 +286,7 @@ Array<string>
 * ``"miss-space-between"``
 * ``"miss-symbol"``
 * ``"missing-global-doc"``
+* ``"missing-local-export-doc"``
 * ``"missing-parameter"``
 * ``"missing-return"``
 * ``"missing-return-value"``
@@ -453,6 +454,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -577,6 +579,8 @@ object<string, string>
     * duplicate-doc-field
     * duplicate-doc-param
     * incomplete-signature-doc
+    * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -813,6 +817,10 @@ object<string, string>
     */
     "missing-global-doc": "None",
     /*
+    Enable diagnostics for exported local function definitions which are not fully annotated.
+    */
+    "missing-local-export-doc": "None",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Any",
@@ -1073,6 +1081,10 @@ object<string, string>
     */
     "missing-global-doc": "Warning",
     /*
+    Enable diagnostics for exported local function definitions which are not annotated.
+    */
+    "missing-local-export-doc": "Warning",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Warning",
diff --git a/doc/zh-cn/config.md b/doc/zh-cn/config.md
@@ -286,6 +286,7 @@ Array<string>
 * ``"miss-space-between"``
 * ``"miss-symbol"``
 * ``"missing-global-doc"``
+* ``"missing-local-export-doc"``
 * ``"missing-parameter"``
 * ``"missing-return"``
 * ``"missing-return-value"``
@@ -453,6 +454,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -578,6 +580,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -814,6 +817,10 @@ object<string, string>
     */
     "missing-global-doc": "None",
     /*
+    Enable diagnostics for exported local function definitions which are not fully annotated.
+    */
+    "missing-local-export-doc": "None",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Any",
@@ -1073,6 +1080,10 @@ object<string, string>
     */
     "missing-global-doc": "Warning",
     /*
+    Enable diagnostics for exported local function definitions which are not annotated.
+    */
+    "missing-local-export-doc": "Warning",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Warning",
diff --git a/doc/zh-tw/config.md b/doc/zh-tw/config.md
@@ -286,6 +286,7 @@ Array<string>
 * ``"miss-space-between"``
 * ``"miss-symbol"``
 * ``"missing-global-doc"``
+* ``"missing-local-export-doc"``
 * ``"missing-parameter"``
 * ``"missing-return"``
 * ``"missing-return-value"``
@@ -453,6 +454,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -578,6 +580,7 @@ object<string, string>
     * duplicate-doc-param
     * incomplete-signature-doc
     * missing-global-doc
+    * missing-local-export-doc
     * undefined-doc-class
     * undefined-doc-name
     * undefined-doc-param
@@ -814,6 +817,10 @@ object<string, string>
     */
     "missing-global-doc": "None",
     /*
+    Enable diagnostics for exported local function definitions which are not fully annotated.
+    */
+    "missing-local-export-doc": "None",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Any",
@@ -1073,6 +1080,10 @@ object<string, string>
     */
     "missing-global-doc": "Warning",
     /*
+    Enable diagnostics for exported local function definitions which are not annotated.
+    */
+    "missing-local-export-doc": "Warning",
+    /*
     Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.
     */
     "missing-parameter": "Warning",
diff --git a/locale/en-us/script.lua b/locale/en-us/script.lua
@@ -120,6 +120,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM         =
 'Missing @param annotation for parameter `{}` in global function `{}`.'
 DIAG_MISSING_GLOBAL_DOC_RETURN        =
 'Missing @return annotation at index `{}` in global function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT  =
+'Missing comment for exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM    =
+'Missing @param annotation for parameter `{}` in exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_RETURN   =
+'Missing @return annotation at index `{}` in exported local function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_PARAM   =
 'Incomplete signature. Missing @param annotation for parameter `{}` in function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_RETURN  =
diff --git a/locale/en-us/setting.lua b/locale/en-us/setting.lua
@@ -381,6 +381,8 @@ config.diagnostics['invisible']             =
 'Enable diagnostics for accesses to fields which are invisible.'
 config.diagnostics['missing-global-doc']    =
 'Missing annotations for globals! Global functions must have a comment and annotations for all parameters and return values.'
+config.diagnostics['missing-local-export-doc'] =
+'Missing annotations for exported locals! Exported local functions must have a comment and annotations for all parameters and return values.'
 config.diagnostics['missing-parameter']     =
 'Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.'
 config.diagnostics['missing-return']        =
diff --git a/locale/pt-br/script.lua b/locale/pt-br/script.lua
@@ -120,6 +120,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM         = -- TODO: need translate!
 'Missing @param annotation for parameter `{}` in global function `{}`.'
 DIAG_MISSING_GLOBAL_DOC_RETURN        = -- TODO: need translate!
 'Missing @return annotation at index `{}` in global function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = -- TODO: need translate!
+'Missing comment for exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM   = -- TODO: need translate!
+'Missing @param annotation for parameter `{}` in exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_RETURN  = -- TODO: need translate!
+'Missing @return annotation at index `{}` in exported local function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_PARAM   = -- TODO: need translate!
 'Incomplete signature. Missing @param annotation for parameter `{}` in function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_RETURN  = -- TODO: need translate!
diff --git a/locale/pt-br/setting.lua b/locale/pt-br/setting.lua
@@ -381,6 +381,8 @@ config.diagnostics['invisible']             = -- TODO: need translate!
 'Enable diagnostics for accesses to fields which are invisible.'
 config.diagnostics['missing-global-doc']    = -- TODO: need translate!
 'Missing annotations for globals! Global functions must have a comment and annotations for all parameters and return values.'
+config.diagnostics['missing-local-export-doc'] = -- TODO: need translate!
+'Missing annotations for exported locals! Exported local functions must have a comment and annotations for all parameters and return values.'
 config.diagnostics['missing-parameter']     = -- TODO: need translate!
 'Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.'
 config.diagnostics['missing-return']        = -- TODO: need translate!
diff --git a/locale/zh-cn/script.lua b/locale/zh-cn/script.lua
@@ -120,6 +120,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM         = -- TODO: need translate!
 'Missing @param annotation for parameter `{}` in global function `{}`.'
 DIAG_MISSING_GLOBAL_DOC_RETURN        = -- TODO: need translate!
 'Missing @return annotation at index `{}` in global function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = -- TODO: need translate!
+'Missing comment for exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM   = -- TODO: need translate!
+'Missing @param annotation for parameter `{}` in exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_RETURN  = -- TODO: need translate!
+'Missing @return annotation at index `{}` in exported local function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_PARAM   = -- TODO: need translate!
 'Incomplete signature. Missing @param annotation for parameter `{}` in function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_RETURN  = -- TODO: need translate!
diff --git a/locale/zh-cn/setting.lua b/locale/zh-cn/setting.lua
@@ -380,6 +380,8 @@ config.diagnostics['invisible']             = -- TODO: need translate!
 'Enable diagnostics for accesses to fields which are invisible.'
 config.diagnostics['missing-global-doc']    = -- TODO: need translate!
 'Missing annotations for globals! Global functions must have a comment and annotations for all parameters and return values.'
+config.diagnostics['missing-local-export-doc'] = -- TODO: need translate!
+'Missing annotations for exported locals! Exported local functions must have a comment and annotations for all parameters and return values.'
 config.diagnostics['missing-parameter']     = -- TODO: need translate!
 'Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.'
 config.diagnostics['missing-return']        = -- TODO: need translate!
diff --git a/locale/zh-tw/script.lua b/locale/zh-tw/script.lua
@@ -120,6 +120,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM         = -- TODO: need translate!
 'Missing @param annotation for parameter `{}` in global function `{}`.'
 DIAG_MISSING_GLOBAL_DOC_RETURN        = -- TODO: need translate!
 'Missing @return annotation at index `{}` in global function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = -- TODO: need translate!
+'Missing comment for exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM   = -- TODO: need translate!
+'Missing @param annotation for parameter `{}` in exported local function `{}`.'
+DIAG_MISSING_LOCAL_EXPORT_DOC_RETURN  = -- TODO: need translate!
+'Missing @return annotation at index `{}` in exported local function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_PARAM   = -- TODO: need translate!
 'Incomplete signature. Missing @param annotation for parameter `{}` in function `{}`.'
 DIAG_INCOMPLETE_SIGNATURE_DOC_RETURN  = -- TODO: need translate!
diff --git a/locale/zh-tw/setting.lua b/locale/zh-tw/setting.lua
@@ -380,6 +380,8 @@ config.diagnostics['invisible']             = -- TODO: need translate!
 'Enable diagnostics for accesses to fields which are invisible.'
 config.diagnostics['missing-global-doc']    = -- TODO: need translate!
 'Missing annotations for globals! Global functions must have a comment and annotations for all parameters and return values.'
+config.diagnostics['missing-local-export-doc'] = -- TODO: need translate!
+'Missing annotations for exported locals! Exported local functions must have a comment and annotations for all parameters and return values.'
 config.diagnostics['missing-parameter']     = -- TODO: need translate!
 'Enable diagnostics for function calls where the number of arguments is less than the number of annotated function parameters.'
 config.diagnostics['missing-return']        = -- TODO: need translate!
diff --git a/script/core/diagnostics/helper/missing-doc-helper.lua 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
diff --git a/script/core/diagnostics/missing-local-export-doc.lua b/script/core/diagnostics/missing-local-export-doc.lua
diff --git a/script/proto/diagnostic.lua b/script/proto/diagnostic.lua
diff --git a/test/diagnostics/init.lua b/test/diagnostics/init.lua
diff --git a/test/diagnostics/missing-local-export-doc.lua b/test/diagnostics/missing-local-export-doc.lua
