Feature Request/How-to: Inlined parameter annotation

[BribeFromTheHive]

I'd like to be able to do inlined type annotation for parameters. It doesn't currently seem to be possible. What I mean is, instead of this:

---@param key                       unknown
---@param callbackFn                fun(Hook, ...):any
---@param priority?                 number
---@param hostTableToHook?          table
---@param defaultNativeBehavior?    function
---@param hookedTableIsMetaTable?   boolean
function Hook.basic(key, callbackFn, priority, hostTableToHook, defaultNativeBehavior, hookedTableIsMetaTable)
    return Hook.add(key, callbackFn, priority, hostTableToHook, defaultNativeBehavior, hookedTableIsMetaTable, true)
end

I'd like to be able to do this:

function Hook.basic(
    key,                    ---@param unknown
    callbackFn,             ---@param fun(Hook, ...):any
    priority,               ---@param? number
    hostTableToHook,        ---@param? table
    defaultNativeBehavior,  ---@param? function
    hookedTableIsMetaTable  ---@param? boolean
)
    return Hook.add(key, callbackFn, priority, hostTableToHook, defaultNativeBehavior, hookedTableIsMetaTable, true)
end

This would cut down on the boilerplate a bit and make the code cleaner.

[C3pa]

IMHO, having only one way to annotate the parameters is better. The proposal doesn't reduce the needed effort by much. Also, it introduced another new concept not existent in the current LuaCATS: ---@param? - another way to annotate optional argument. I am against that.

[BribeFromTheHive]

IMHO, having only one way to annotate the parameters is better. The proposal doesn't reduce the needed effort by much. Also, it introduced another new concept not existent in the current LuaCATS: ---@param? - another way to annotate optional argument. I am against that.

That is totally valid. I am only putting out opinions. I am leaning more towards TSTL for the longer term at this point, as I don’t think that EmmyLua’s JSDoc-type stuff is convenient for quick coding.

[Frityet]

IMHO, having only one way to annotate the parameters is better. The proposal doesn't reduce the needed effort by much. Also, it introduced another new concept not existent in the current LuaCATS: ---@param? - another way to annotate optional argument. I am against that.

That is totally valid. I am only putting out opinions. I am leaning more towards TSTL for the longer term at this point, as I don’t think that EmmyLua’s JSDoc-type stuff is convenient for quick coding.

Check out teal

[Frityet]

IMHO, having only one way to annotate the parameters is better. The proposal doesn't reduce the needed effort by much. Also, it introduced another new concept not existent in the current LuaCATS: ---@param? - another way to annotate optional argument. I am against that.

---@param x integer
---@param y integer?
local function my_function(x, y)

end
``` why `?` on the `param`

[sumneko]

It might be possible to support ---@type. However, since it's only a syntax sugar proposal, I won't consider adding support for it at the moment.

[Congee]

Is there anyway to type annotate a function that is an expression? This proposal is probably the only solution to the problem. Correct me if I'm wrong; I have not found a solution.

--- function assignment in a statement
--- @param callback fun(arg: string)
local fn = function(callback) end;
fn(function(arg)end); -- arg is of type string

--- function in a table of a union type, not working
--- @type (string | fun(arg: string))[]
local tbl = { function(arg) end }; -- arg is of type any

--- function as an expression, not working
--- @type fun(arg: string)
function(arg) end; -- arg is of type any

--- type coercion, not working
function(arg) end --[[@as fun(arg: string)]] -- arg is of type any

This proposal is not a syntactic sugar if there isn't an alternative.

Edit: a cumbersome proxy solution could be

--- proxy solution
function(__arg)
  --- @type fun(arg: string)
  local fn = function(arg) end; -- arg is of type string
  return fn(__arg);
end

[BribeFromTheHive]

Your second example looks like you didn't properly assign the type of the variable, because you wrapped the function to a table holding the function at index [1]

[Congee]

Your second example looks like you didn't properly assign the type of the variable, because you wrapped the function to a table holding the function at index [1]

Thanks, I updated it to --- @type (string | fun(arg: string))[]

[tomlau10]

For the array of function case, I think it is a bug and it is reported in this issue: #2367
The current workaround is to add the array index in both the annotation and the literal table:

--- @type table<integer, fun(arg: string)>
local tbl = { [1] = function(arg) end }; --> arg: string

I have debugged into it before and proposed a fix here: #2367 (comment), but it is incomplete.
Maybe you or others would like to pick up from there 😕

---

As for the expression case, I don't quite understand the use case?
You cannot just write anonymous function on itself?

• Anyway I tried and seems you can just use @param on it?

--- @param arg string
(function(arg)
    --> arg: string
end)(1) --> param-type-mismatch: Cannot assign `integer` to parameter `string`.

• the following is a syntax error, but the type infer still works

--- proxy solution
function(__arg)
    --- @param arg string
    local fn = function(arg) end; --> arg: string
    return fn(__arg);
end

-- executing this above will throw error
-- lua: c:\Users\TomLau\test\test.lua:2: <name> expected near '('

[Congee]

For the array of function case, I think it is a bug and it is reported in this issue: #2367 The current workaround is to add the array index in both the annotation and the literal table:

--- @type table<integer, fun(arg: string)>
local tbl = { [1] = function(arg) end }; --> arg: string

I have debugged into it before and proposed a fix here: #2367 (comment), but it is incomplete. Maybe you or others would like to pick up from there 😕

As for the expression case, I don't quite understand the use case? You cannot just write anonymous function on itself?

* Anyway I tried and seems you can just use `@param` on it?

--- @param arg string
(function(arg)
    --> arg: string
end)(1) --> param-type-mismatch: Cannot assign `integer` to parameter `string`.

* the following is a syntax error, but the type infer still works

--- proxy solution
function(__arg)
    --- @param arg string
    local fn = function(arg) end; --> arg: string
    return fn(__arg);
end

-- executing this above will throw error
-- lua: c:\Users\TomLau\test\test.lua:2: <name> expected near '('

Thank you very much for workarounds. Your 2nd snippet though different from my use case - where I tried to type annotation the function expression as a whole - it is yet more related to this thread. Any way I am pretty happy with your solutions.