Annotating to require extra parameters

[Rouneq]

In the game system I'm writing for, values returned from a function actually require an extra set of parenthesis to get the "real" return value. The call returns userdata and having Lua evaluate that data into something usable is what the extra parens force. As an example, let's say there's a Navigation namespace with a function PathExists(x, y, z). Making a call like

local canIReachIt = Navigation.PathExists(10, 20, 5)

if (canIReachIt) then
    print('Yes!')
else
    print('You're stuck')
end

will only work if I have an extra set of parens on the call (i.e., PathExists(10, 20, 5)()).

The method is currently annotated as

--- Returns true if the specified navigation parameters results in a navigatable path.
---@param x number
---@param y number
---@param z number
---@return boolean
function Navigation.PathExists(x, y, z) end

Is there a way to modify this annotation to have the language server prompt me for the extra?

[carsakiller]

This should do the trick:

--- Returns true if the specified navigation parameters results in a navigatable path.
---@param x number
---@param y number
---@param z number
---@return fun(): boolean
function Navigation.PathExists(x, y, z) end

local exists = Navigation.PathExists(10, 20, 30)()

[Rouneq]

Sadly no. The language server didn't make a fuss about missing parens.

[carsakiller]

I don't think there is a way to force a user to call a function. The best I can think of is to add nodiscard as it will force the user to do something with the result, either call it or assign it.

--- Returns true if the specified navigation parameters results in a navigatable path.
---@param x number
---@param y number
---@param z number
---@return fun(): boolean
---@nodiscard
function Navigation.PathExists(x, y, z) end
local exists = Navigation.PathExists(10, 20, 30)

[Rouneq]

Ultimately, the language server can't force anyone to do anything regardless of how many error/warning/info messages are given. What it can do is provide those error/warning/info messages. I can decide to act upon them. And that's what I'm looking for. A way to get a message in the first place so I can do the necessary thing to get the legitimate results I can act on.

[carsakiller]

I believe this is the best method available for that. The @return marks the return value as a function, which should give the user a hint to call it. @nodiscard will warn the user that they cannot do nothing with the return value - until they either assign it to a variable or call it.