Standard way to annotate `---@return void` - aka "does not return anything"?

[mycroftjr]

How would one annotate that a function does not return anything in the current version of LuaLS? Note that this is subtly different from returning nil (https://stackoverflow.com/a/18526055/7376471).

[tomlau10]

I just tested a bit, and seems currently you may use ---@type fun() to specify a function with no return value

---@type fun()
function a()
    return nil --<< redundant-return-value warning here
end

---

However as far as I know, the ---@type is not compatible with ---@param. So if your function contains params then you have to specify them through the fun() annotation syntax.

---@type fun(b: integer)
function a(b) --<< `b` will be inferred as integer
    return
end

[mycroftjr]

I just tested a bit, and seems currently you may use ---@type fun() to specify a function with no return value

---@type fun()
function a()
    return nil --<< redundant-return-value warning here
end

However as far as I know, the ---@type is not compatible with ---@param. So if your function contains params then you have to specify them through the fun() annotation syntax.

---@type fun(b: integer)
function a(b) --<< `b` will be inferred as integer
    return
end

That's so gross, thanks lol Also it still doesn't cause any errors if you try to "use" the "return value" - the "type" of which is unknown

[bavalpey]

---@type is definitely compatible with ---@param

[mycroftjr]

---@type is definitely compatible with ---@param

It still doesn't work all that well, since the ---@type fun(foo, bar) erases the parameter type information for the caller (or at least for the function hover popup) So for full documentation, you do have to shove all the type information into the @type line and it just feels bad and still doesn't provide any "you shouldn't be trying to use the return value of this function" warnings

[bavalpey]

Seems like you want the opposite of ---@nodiscard?

Shouldn't explicitly writing nil as the return type do that? There's almost 0 runtime difference between return and return nil

To implement this, we need support for a NeverType, that is, a type that can never exist at runtime.

And I'm not even sure that would do anything. Not sure if difference between empty and nil as a return is fully specified..

[tomlau10]

Also it still doesn't cause any errors if you try to "use" the "return value" - the "type" of which is unknown

The current version of LuaLS seems doesn't have a specific check for "getting extra return value from a function", and those extra variables will just be of unknown type. I know there is a no-unknown diagnostics which is disabled by default, you might try to turn it on in your settings.json / .luarc.json .

"Lua.diagnostics.neededFileStatus": {
    "no-unknown": "Any!",
},

But warn you it's too strict and after enabling it, your workspace might be full of these kinds of errors, unless your codebase is fully annotated. 🙈