diff --git a/changelog.md b/changelog.md index b6caa5050..4b6716deb 100644 --- a/changelog.md +++ b/changelog.md @@ -2,6 +2,7 @@ ## Unreleased +* `NEW` diagnostic: `missing-local-doc` ## 3.16.0 `2025-12-2` diff --git a/doc/en-us/config.md b/doc/en-us/config.md index 6e6a5bcae..d99570c54 100644 --- a/doc/en-us/config.md +++ b/doc/en-us/config.md @@ -314,6 +314,7 @@ Array * ``"miss-symbol"`` * ``"missing-fields"`` * ``"missing-global-doc"`` +* ``"missing-local-doc"`` * ``"missing-local-export-doc"`` * ``"missing-parameter"`` * ``"missing-return"`` @@ -504,6 +505,7 @@ object * duplicate-doc-param * incomplete-signature-doc * missing-global-doc + * missing-local-doc * missing-local-export-doc * undefined-doc-class * undefined-doc-name @@ -633,6 +635,7 @@ object * duplicate-doc-param * incomplete-signature-doc * missing-global-doc + * missing-local-doc * missing-local-export-doc * undefined-doc-class * undefined-doc-name @@ -870,6 +873,10 @@ object */ "missing-global-doc": "None", /* + Missing annotations for locals! Local functions must have a comment and annotations for all parameters and return values. + */ + "missing-local-export-doc": "None", + /* Missing annotations for exported locals! Exported local functions must have a comment and annotations for all parameters and return values. */ "missing-local-export-doc": "None", diff --git a/locale/en-us/script.lua b/locale/en-us/script.lua index f8a38b9ab..229109dbc 100644 --- a/locale/en-us/script.lua +++ b/locale/en-us/script.lua @@ -126,6 +126,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_DOC_COMMENT = +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = +'Missing @return annotation at index `{}` in local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = 'Missing comment for exported local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM = diff --git a/locale/en-us/setting.lua b/locale/en-us/setting.lua index 0c136333a..cd9c305bc 100644 --- a/locale/en-us/setting.lua +++ b/locale/en-us/setting.lua @@ -411,6 +411,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-doc'] = +'Missing annotations for locals! Local 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'] = diff --git a/locale/es-419/script.lua b/locale/es-419/script.lua index b3be7c855..ba60646d8 100644 --- a/locale/es-419/script.lua +++ b/locale/es-419/script.lua @@ -120,6 +120,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM = 'Falta una anotación @param para el parámetro `{}` en la función global `{}`.' DIAG_MISSING_GLOBAL_DOC_RETURN = 'Falta una anotación @return para el índice `{}` en la función global `{}`.' +DIAG_MISSING_LOCAL_DOC_COMMENT = -- TODO: need translate! +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = -- TODO: need translate! +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = -- TODO: need translate! +'Missing @return annotation at index `{}` in local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = 'Falta un un comentario para la función local exportada `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM = diff --git a/locale/es-419/setting.lua b/locale/es-419/setting.lua index f6d92f451..a0e2d63b3 100644 --- a/locale/es-419/setting.lua +++ b/locale/es-419/setting.lua @@ -413,6 +413,8 @@ config.diagnostics['invisible'] = 'Habilita el diagnóstico para accesos a campos que son invisibles.' config.diagnostics['missing-global-doc'] = 'Habilita el diagnóstico para globales faltantes. Las funciones globales deben tener un comentario y anotaciones para todos sus parámetros y valores retornados.' +config.diagnostics['missing-local-doc'] = -- TODO: need translate! +'Missing annotations for locals! Local functions must have a comment and annotations for all parameters and return values.' config.diagnostics['missing-local-export-doc'] = 'Habilita el diagnóstico para locales exportadas. Las funciones locales deben tener un comentario y anotaciones para todos sus parámetros y valores retornados.' config.diagnostics['missing-parameter'] = diff --git a/locale/ja-jp/script.lua b/locale/ja-jp/script.lua index 36c8265c8..75b6b57cf 100644 --- a/locale/ja-jp/script.lua +++ b/locale/ja-jp/script.lua @@ -122,6 +122,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM = 'グローバル関数 `{2}` のパラメータ `{1}` に @param 注釈がありません。' DIAG_MISSING_GLOBAL_DOC_RETURN = 'グローバル関数 `{2}` の第 `{1}` の戻り値に @return 注釈がありません。' +DIAG_MISSING_LOCAL_DOC_COMMENT = -- TODO: need translate! +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = -- TODO: need translate! +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = -- TODO: need translate! +'Missing @return annotation at index `{}` in local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = 'エクスポートされたローカル関数 `{}` に注釈がありません。' DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM = diff --git a/locale/ja-jp/setting.lua b/locale/ja-jp/setting.lua index d9d2031ea..d0f864dcb 100644 --- a/locale/ja-jp/setting.lua +++ b/locale/ja-jp/setting.lua @@ -411,6 +411,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-doc'] = -- TODO: need translate! +'Missing annotations for locals! Local 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! diff --git a/locale/pt-br/script.lua b/locale/pt-br/script.lua index 64fbf40f9..787425748 100644 --- a/locale/pt-br/script.lua +++ b/locale/pt-br/script.lua @@ -122,6 +122,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_DOC_COMMENT = -- TODO: need translate! +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = -- TODO: need translate! +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = -- TODO: need translate! +'Missing @return annotation at index `{}` in local 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! diff --git a/locale/pt-br/setting.lua b/locale/pt-br/setting.lua index 037340ec1..9178ea0b0 100644 --- a/locale/pt-br/setting.lua +++ b/locale/pt-br/setting.lua @@ -411,6 +411,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-doc'] = -- TODO: need translate! +'Missing annotations for locals! Local 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! diff --git a/locale/zh-cn/script.lua b/locale/zh-cn/script.lua index ee0262d8b..55c383760 100644 --- a/locale/zh-cn/script.lua +++ b/locale/zh-cn/script.lua @@ -126,6 +126,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM = '全局函数 `{2}` 的参数 `{1}` 缺少 @param 注解。' DIAG_MISSING_GLOBAL_DOC_RETURN = '全局函数 `{2}` 的第 `{1}` 个返回值缺少 @return 注解。' +DIAG_MISSING_LOCAL_DOC_COMMENT = -- TODO: need translate! +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = -- TODO: need translate! +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = -- TODO: need translate! +'Missing @return annotation at index `{}` in local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = '导出的局部函数 `{}` 缺少注释。' DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM = diff --git a/locale/zh-cn/setting.lua b/locale/zh-cn/setting.lua index 1e6ef7db6..cce23d40e 100644 --- a/locale/zh-cn/setting.lua +++ b/locale/zh-cn/setting.lua @@ -409,6 +409,8 @@ config.diagnostics['invisible'] = '使用不可见的值' config.diagnostics['missing-global-doc'] = '全局变量的注释缺失(全局函数必须为所有参数和返回值提供注释和注释)' +config.diagnostics['missing-local-doc'] = -- TODO: need translate! +'Missing annotations for locals! Local functions must have a comment and annotations for all parameters and return values.' config.diagnostics['missing-local-export-doc'] = '导出的本地函数缺少注释(导出的本地函数必须有包括本身以及所有参数和返回值的注释)' config.diagnostics['missing-parameter'] = diff --git a/locale/zh-tw/script.lua b/locale/zh-tw/script.lua index 15639c954..0c70387a2 100644 --- a/locale/zh-tw/script.lua +++ b/locale/zh-tw/script.lua @@ -122,6 +122,12 @@ DIAG_MISSING_GLOBAL_DOC_PARAM = '全域函式 `{2}` 的參數 `{1}` 缺少 @param 標註。' DIAG_MISSING_GLOBAL_DOC_RETURN = '全域函式 `{2}` 的第 `{1}` 個回傳值缺少 @return 標註。' +DIAG_MISSING_LOCAL_DOC_COMMENT = -- TODO: need translate! +'Missing comment for local function `{}`.' +DIAG_MISSING_LOCAL_DOC_PARAM = -- TODO: need translate! +'Missing @param annotation for parameter `{}` in local function `{}`.' +DIAG_MISSING_LOCAL_DOC_RETURN = -- TODO: need translate! +'Missing @return annotation at index `{}` in local function `{}`.' DIAG_MISSING_LOCAL_EXPORT_DOC_COMMENT = '輸出的區域函式 `{}` 缺少註解。' DIAG_MISSING_LOCAL_EXPORT_DOC_PARAM = diff --git a/locale/zh-tw/setting.lua b/locale/zh-tw/setting.lua index 51ba06b7d..bd76c2a35 100644 --- a/locale/zh-tw/setting.lua +++ b/locale/zh-tw/setting.lua @@ -409,6 +409,8 @@ config.diagnostics['invisible'] = '嘗試存取不可見的欄位' config.diagnostics['missing-global-doc'] = '全域變數缺少標註（全域函式必須為所有參數和回傳值提供標註）' +config.diagnostics['missing-local-doc'] = -- TODO: need translate! +'Missing annotations for locals! Local functions must have a comment and annotations for all parameters and return values.' config.diagnostics['missing-local-export-doc'] = '匯出的區域函式缺少標註（匯出的區域函式、所有的參數和回傳值都必須有標註）' config.diagnostics['missing-parameter'] = diff --git a/script/core/diagnostics/missing-local-doc.lua b/script/core/diagnostics/missing-local-doc.lua new file mode 100644 index 000000000..93656530c --- /dev/null +++ b/script/core/diagnostics/missing-local-doc.lua @@ -0,0 +1,27 @@ +local files = require 'files' +local guide = require 'parser.guide' +local await = require 'await' +local helper = require 'core.diagnostics.helper.missing-doc-helper' + +---@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, 'function', function (source) + await.delay() + + if source.parent.type ~= 'local' then return end + + helper.CheckFunction(source, callback, 'DIAG_MISSING_LOCAL_DOC_COMMENT', 'DIAG_MISSING_LOCAL_DOC_PARAM', + 'DIAG_MISSING_LOCAL_DOC_RETURN') + end) +end diff --git a/script/proto/diagnostic.lua b/script/proto/diagnostic.lua index 72761493e..0e7817afd 100644 --- a/script/proto/diagnostic.lua +++ b/script/proto/diagnostic.lua @@ -106,6 +106,7 @@ m.register { m.register { 'incomplete-signature-doc', 'missing-global-doc', + 'missing-local-doc', 'missing-local-export-doc', } { group = 'luadoc', diff --git a/test/diagnostics/init.lua b/test/diagnostics/init.lua index fc97e4389..4e15ec121 100644 --- a/test/diagnostics/init.lua +++ b/test/diagnostics/init.lua @@ -101,6 +101,7 @@ check 'invisible' check 'lowercase-global' check 'missing-fields' check 'missing-global-doc' +check 'missing-local-doc' check 'missing-local-export-doc' check 'missing-parameter' check 'missing-return-value' diff --git a/test/diagnostics/missing-local-doc.lua b/test/diagnostics/missing-local-doc.lua new file mode 100644 index 000000000..a3934132e --- /dev/null +++ b/test/diagnostics/missing-local-doc.lua @@ -0,0 +1,28 @@ +TEST [[ +local + +---comment +local function fl1() +end +]] + +TEST [[ +local function fl0() +end + +---@param p integer +local function fl1(p) +end +]] + +TEST [[ +local function fl0() + return +end + +---@return integer +local function fl1() + return 42 +end +]]