Lua: improve vim.keymap.set()

[justinmk]

Problem

keymap.set has a suboptimal signature, it could be improved

Expected behavior

• add an overloaded signature so that the rhs can be the last arg. function keymap.set(mode, lhs, opts, rhs)
  • Callback should always be the last arg, where possible. That is a readability enhancement and a project standard.
  • The old signature will also be supported. but discouraged
• lhs can be a list. This reduces boilerplate when defining aliases for a mapping.

Comparison

Before:

vim.keymap.set('n', 'crr', function()
  vim.lsp.buf.code_action()
end, { desc = 'vim.lsp.buf.code_action()' })

After:

vim.keymap.set('n', 'crr', { desc = 'vim.lsp.buf.code_action()' }, function()
  vim.lsp.buf.code_action()
end)

[justinmk]

What is the objection to this?

[clason]

Personally, I don't see the claimed readability benefit, so the churn seems not worth it. And it conflicts with the (in my opinion stronger) project standard of "optional keyword-style arguments last".

[mfussenegger]

No objection from my side, but I suspect part of the objection is that in most personal keymaps people just don't set a description, so they already have:

vim.keymap.set('n', 'crr', function()
  vim.lsp.buf.code_action()
end)

And with this change they'd have to write:

vim.keymap.set('n', 'crr', nil, function()
  vim.lsp.buf.code_action()
end)

The nudge towards adding a description might not be the worst, but imho there's no clear advantage to the proposed change for most users.
Besides, in this particular case one could just write:

vim.keymap.set('n', 'crr', vim.lsp.buf.code_action, { desc = 'vim.lsp.buf.code_action()' })

Opposed to autocmds, keymaps don't (yet?) provide a context as argument to the called function, so using the function reference is currently save.

[justinmk]

And with this change they'd have to write:

vim.keymap.set('n', 'crr', nil, function()
  vim.lsp.buf.code_action()
end)

good point. so instead, I have updated the proposal to be an overload instead of deprecating the old form.