Feature Request: Do not diagnose unused-local for function parameters

This is a feature request for a new setting for LLS which would not diagnose unused-local for variables which are parameters of a function. Something like

"Lua.diagnostics.unusedLocalExcludeFuncParam": true

The reason I'd like this feature is because we have a Lua codebase that heavily relies on something similar to virtual functions, where there are many tables that have functions defined that share the same name and list of parameters, but some of these functions don't need to use all of the parameters. Think of something like this

function menu1:on_select_item(item, mouse_button) do_something_with_item(item) end
function menu2:on_select_item(item, mouse_button) do_something_with_mouse_button(mouse_button) end

Of course this could be changed to appeal to the current unused-local diagnostics by changing it to

function menu1:on_select_item(item) do_something_with_item(item) end
function menu2:on_select_item(_, mouse_button) do_something_with_mouse_button(mouse_button) end

but, besides doing the fixup being a lot of work, it makes maintenance of the code base worse because a programmer can't easily know anymore what those _ parmeters are supposed to be. Another alternative would be to add all known function parameter names to "Lua.diagnostics.unusedLocalExclude" (introduced via #619) but of course that also would be sub-optimal, because ignoring generic names like item could defeat the purpose of the diagnostic.

Besides function parameters, having an option to ignore for-loop variables would also be very neat. It's often easier there to substitute the name for _ but still, sometimes that loses important information on what the key/value of a for-loop over pairs(...) is. So something like

"Lua.diagnostics.unusedLocalExcludeForLoopVars": true

would also be very appreciated.

Thank you for your consideration, and of course for making LLS, it's awesome!

(unrelated to the feature request)

Our team setup both LLS and luacheck for linting project files, and we use luacheck to check for unused locals.
https://github.com/lunarmodules/luacheck

It has more fine-grained control on which variables to check for unused.
https://luacheck.readthedocs.io/en/stable/warnings.html#unused-variables-2xx-and-values-3xx

For example here is the .luacheckrc that we use:

std = "lua53c"
quiet = 1
codes = true
cache = true
max_line_length = 150
unused_args = false
unused_secondaries = false
ignore = {
    "311",  -- value assigned but unused
    "312",  -- unused argument value
    "431",  -- shadowing upvalue
    "423",  -- shadowing loop variables
    "432",  -- shadowing upvalue argument
    "512",  -- loop executed at most once
    "542",  -- empty if branch
}

Then we kept the severity of LLS's unused-local as hint level only (for the grey out effect in vscode)

Hope this helps a bit before this feature is implemented is LLS 😄

You can actually set a glob pattern for unusedLocalExclude

I used: diagnostics.unusedLocalExclude = {"_*"}

This lets me simply prefix any unused variables with an underscore. That way I can safely ignore them, but I can still provide meaningful names when needed:

This works for functions and for loops.

local function something(arg1, _arg2)
	print(arg1)
end

something(1, 2)

for _idx, name in pairs(sometable) do
    print(name)
end

I would also love this feature. I make heavy use of such callbacks/listeners and not having to litter my code with ---@diagnostic disable-line: unused-local would be great.

I can not make use of the suggested _* glob because I use underscores to denote class-private variables. I know it doesn't make sense for a function argument to be class-private, but I still feel that would be confusing.

@ActivexDiamond

@ActivexDiamond could you use the @private or @protected annotation for your private/protected members of a class. https://luals.github.io/wiki/annotations/#private

You might also be able to play with the glob pattern to find something that is more suitable to your existing code base.

I know neither of these two suggestions are the actual feature, but maybe they'll help you in the meantime.

Navigation Menu

Repository navigation

Feature Request: Do not diagnose unused-local for function parameters #3166

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: Do not diagnose unused-local for function parameters #3166

Description

Activity

tomlau10 commented on Apr 25, 2025

kcx1 commented on Nov 25, 2025

ActivexDiamond commented on Dec 16, 2025

kcx1 commented on Dec 16, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions