Specify variable return type

[carsakiller]

Currently, you cannot specify the type (or name) of a variable @return:

---@return ... Description!

---This is not allowed
---@return ... string Description!

This problem is more complex than just adding that ability though, take string.match() as an example:

string.match() is defined as returning ..., meaning its returns are marked as unknown. When using the no-unknown diagnostic, this results in a warning/error. In reality, it can only ever return string(s) or nil:

local text = "Key: 123456789"

local match = string.match(text, "Key: (%d+)")
print(match) -- 123456789


local match, match2 = string.match(text, "(Key): (%d+)")
print(match, match2) -- Key, 123456789


local match = string.match(text, "Pass: (%d+)")
print(match) -- nil

So maybe a new syntax should be introduced:
---@return nil|string... match Description!
or
---@return string|nil ... Description!

This would then result in the following:

local match, match2 = string.match(foo, bar)
-- match -> nil | string
-- match2 -> nil | string

[flrgh]

Unless I'm misunderstanding something, I am not seeing this problem myself. This is working for me:

---@return number a
---@return table  b
---@return string ...
local function f() end

local a, b, c, d = f()

Hover returns the expected results for each value as well (a => number, b => table, c and d => string)

[flrgh]

Oooh I see. I think the string.match annotation just needs an update:

https://github.com/sumneko/lua-language-server/blob/8365eec4f4baa429d1f8a0d2f63132df8902db88/meta/template/string.lua#L86-L92

Should be ---@return any ... or similar.

[flrgh]

Also, a feature of string.match that has egregiously poor documentation is that it can in fact return number/integer types as well.

See the Captures subsection in the Lua manual:

As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.

So I think the correct annotation would be ---@return string|integer|nil ....

[carsakiller]

Also, a feature of string.match that has egregiously poor documentation is that it can in fact return number/integer types as well.

Riiight, I remember reading about that a long time ago and then proceeding to never use it 😄. Good catch!

[carsakiller]

While I am at fixing the annotation, any other examples you can find of the old variable return syntax?

[carsakiller]

I don't use any of the 3rd party libraries that are included so I don't know if any of those are incorrect.

These are all the references I could find for @return ...:

[flrgh]

I'm only familiar with OpenResty, and I can confirm this return type is incorrect (should be ---@return any ...).

Actually, I think any that are missing a type for ... can probably just be corrected to ---@return any ... without too much fuss, since they're already broken. You're welcome to tag me on your PR if you'd like a second set of 👀 on it though.

[sumneko]

Also, a feature of string.match that has egregiously poor documentation is that it can in fact return number/integer types as well.

See the Captures subsection in the Lua manual:

As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.

So I think the correct annotation would be ---@return string|integer|nil ....

This causes some type checking issues.

[carsakiller]

That isn't technically wrong though, is it? x could be nil or an integer if a match was not found or an index was returned. It would then be on the user to either @type x string if they are certain it will always be a string, or confirm it by checking its type()