Feature Request: Annotate Type of Return Statement

[firas-assaad]

I already posted this idea in a discussion #1656, but I thought I'd formally request the feature here as well

I have module Lua files with data in a structured format, and I'd like to explicitly annotate the returned value. I tried the following:

-- module A

---@alias My_Format { x : integer, y: integer }

---@type My_Format
return {
    x = 1,
    y = 'hello', -- no warnings
}

This doesn't perform any checking on the return type. Instead, I can annotate a local variable and return it:

---@type My_Format
local result = {
    x = 1,
    y = 'hello' -- warning: assign-type-mismatch
}

return result

Using a local variable isn't a big deal, but it forces me to structure code differently just to accommodate the language server. It would be nice if it understood the annotation before the return statement.

Another similar case is with a function call instead of modules:

---@alias My_Format { x : integer, y: integer }

local function x()
    ---@type My_Format
    return {
        x = 'hi' -- No completion or type checking
    } -- using --[[@as My_Format]] doesn't work either
end

local y = x() -- type of y is just `table`

Here, one solution is to annotate the function directly with @return, but that doesn't solve the type-checking/completion issue.

[cwrau]

This would also help with nvim config, because in https://github.com/folke/lazy.nvim#examples you specify the plugins just via files with a return

[filipekiss]

This would also help with nvim config, because in folke/lazy.nvim#examples you specify the plugins just via files with a return

@cwrau This is the exact reason why I wanted this

[13k]

Also encountering this issue when configuring lazy.nvim, but I found a (mental) workaround, by structuring single-plugin config files like this:

--- @module "lazy.types"

--- @type LazySpec
local M = {
  "plugin-url",
  -- basic settings
}

-- Here the LS correctly detects `opts` signature.
-- Parameters and return types are also detected correctly, there's no need to annotate them
--   `self` has type `LazyPlugin`
--   `options` has type `table`
function M:config(options)
  -- ...
end

-- Obviously, this works for all `LazySpec` fields (cond, opts, keys, etc)

return M

This works for complex plugins where I need functions for these fields. For simple plugins which don't need configuration, I group them in some arbitrary file and I have to use

--- @module "lazy.types"

--- @type LazySpec
local M = {
  {
    "plugin1",
    -- ...
  },
  {
    "plugin2",
    -- ...
  },
}

return M

Which is not ideal, like you already commented.

[firas-assaad]

Thanks for implementing this! 🙏