Skip to content

Unannotated local function diagnostic #3300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
NathanSnail wants to merge 7 commits into
base: master
Choose a base branch
from
Draft

Unannotated local function diagnostic #3300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7dc8713
feat(diagnostics): add missing local doc implementation for english
NathanSnail Dec 2, 2025
e6084bc
test(diagnostics): add return diagnostics for missing-local-doc
NathanSnail Dec 2, 2025
349ce8e
chore(diagnostics): add needs translation notes to all languages for …
NathanSnail Dec 2, 2025
2242fb4
chore(diagnostics): add needs translation notes to all languages docu…
NathanSnail Dec 2, 2025
931934a
chore(diagnostics): add missing-local-doc to changelog
NathanSnail Dec 2, 2025
ad9ee6d
Merge branch 'master' into unannotated_function_diagnostic
NathanSnail Dec 2, 2025
2c574f1
fix(diagnostics): remove duplicate translations for missing-local-doc…
NathanSnail Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased
<!-- Add all new changes here. They will be moved under a version at release -->
* `NEW` diagnostic: `missing-local-doc`

## 3.16.0
`2025-12-2`
Expand Down
7 changes: 7 additions & 0 deletions doc/en-us/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,7 @@ Array<string>
* ``"miss-symbol"``
* ``"missing-fields"``
* ``"missing-global-doc"``
* ``"missing-local-doc"``
* ``"missing-local-export-doc"``
* ``"missing-parameter"``
* ``"missing-return"``
Expand Down Expand Up @@ -504,6 +505,7 @@ object<string, string>
* duplicate-doc-param
* incomplete-signature-doc
* missing-global-doc
* missing-local-doc
* missing-local-export-doc
* undefined-doc-class
* undefined-doc-name
Expand Down Expand Up @@ -633,6 +635,7 @@ object<string, string>
* duplicate-doc-param
* incomplete-signature-doc
* missing-global-doc
* missing-local-doc
* missing-local-export-doc
* undefined-doc-class
* undefined-doc-name
Expand Down Expand Up @@ -870,6 +873,10 @@ object<string, string>
*/
"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",
Copy link

@gemini-code-assist gemini-code-assist bot Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There seems to be a copy-paste error here. The diagnostic name should be missing-local-doc to match the comment above, but it's written as missing-local-export-doc. This also creates a duplicate key in this configuration block, as missing-local-export-doc is defined again on line 882.

Suggested change
"missing-local-export-doc": "None",
"missing-local-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",
Expand Down
6 changes: 6 additions & 0 deletions locale/en-us/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
2 changes: 2 additions & 0 deletions locale/en-us/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =
Expand Down
6 changes: 6 additions & 0 deletions locale/es-419/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
2 changes: 2 additions & 0 deletions locale/es-419/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =
Expand Down
6 changes: 6 additions & 0 deletions locale/ja-jp/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
2 changes: 2 additions & 0 deletions locale/ja-jp/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
6 changes: 6 additions & 0 deletions locale/pt-br/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
2 changes: 2 additions & 0 deletions locale/pt-br/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
6 changes: 6 additions & 0 deletions locale/zh-cn/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
2 changes: 2 additions & 0 deletions locale/zh-cn/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =
Expand Down
6 changes: 6 additions & 0 deletions locale/zh-tw/script.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
2 changes: 2 additions & 0 deletions locale/zh-tw/setting.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =
Expand Down
27 changes: 27 additions & 0 deletions script/core/diagnostics/missing-local-doc.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions script/proto/diagnostic.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ m.register {
m.register {
'incomplete-signature-doc',
'missing-global-doc',
'missing-local-doc',
'missing-local-export-doc',
} {
group = 'luadoc',
Expand Down
1 change: 1 addition & 0 deletions test/diagnostics/init.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
28 changes: 28 additions & 0 deletions test/diagnostics/missing-local-doc.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
TEST [[
local <!function fl0()
end!>

---comment
local function fl1()
end
]]

TEST [[
local function fl0(<!p!>)
end

---@param p integer
local function fl1(p)
end
]]

TEST [[
local function fl0()
return <!42!>
end

---@return integer
local function fl1()
return 42
end
]]
Loading