Lua中如何为函数类型定义添加参数描述并保留智能提示？

核心方案：带参数注释的函数类型别名 #

问题出在你最初定义MapperFunction时只声明了参数类型，没有附带描述注释。LuaLS（Lua Language Server）支持在函数类型别名中直接为每个参数添加注释，后续用---@type标注函数时，这些参数描述会被完整继承，不会丢失IntelliSense提示。

示例代码如下：

-- 先定义依赖的基础类型
---@alias MapRHS string|fun()  -- 映射右侧动作：可为命令字符串或回调函数
---@class MapOptions
---@field noremap boolean? 是否禁用递归映射
---@field silent boolean? 是否隐藏映射触发的命令输出
---@field expr boolean? 是否将右侧内容作为表达式执行

-- 带参数注释的映射函数类型别名
---@alias MapperFunction fun(
---  desc: string, -- 映射功能描述，用于which-key提示或文档生成
---  lhs: string, -- 触发映射的按键组合（遵循Neovim按键语法）
---  rhs: MapRHS, -- 映射触发后执行的动作
---  opts: MapOptions? -- 可选配置项，覆盖默认映射行为
---)

-- 正常模式映射函数，标注为MapperFunction
--- 正常模式下的按键映射封装
---@type MapperFunction
local nmap = function(desc, lhs, rhs, opts)
  opts = opts or {}
  opts.desc = desc
  vim.keymap.set('n', lhs, rhs, opts)
end

-- 插入模式映射函数，复用同一类型别名
--- 插入模式下的按键映射封装
---@type MapperFunction
local imap = function(desc, lhs, rhs, opts)
  opts = opts or {}
  opts.desc = desc
  vim.keymap.set('i', lhs, rhs, opts)
end

柯里化场景的兼容处理 #

如果你用柯里化函数批量生成模式映射，只需给柯里化的返回值标注MapperFunction，同样能保留参数提示：

--- 创建指定模式的映射生成器
---@param mode string|string[] 目标Neovim模式（如'n'/'i'/'v'）
---@return MapperFunction
local function create_mapper(mode)
  return function(desc, lhs, rhs, opts)
    opts = opts or {}
    opts.desc = desc
    vim.keymap.set(mode, lhs, rhs, opts)
  end
end

---@type MapperFunction
local nmap = create_mapper('n')
---@type MapperFunction
local vmap = create_mapper('v')

关键说明 #

• 确保使用最新版LuaLS，旧版本可能不支持函数类型别名中的参数注释继承。
• 类型别名中的参数注释会被LuaLS解析，在IntelliSense中显示完整的参数类型+描述信息，完全贴合你TypeScript背景下的类型定义习惯。

内容的提问来源于stack exchange，提问作者Sir Wrexes