Set desc for all mappings we set.

And ensure we hopefully always will via a test.

In particular this means that which-key users should now see a
description of what each of our mappings do.

Author: Julian

lua/lean/init.lua

@@ -16,22 +16,71 @@ local subprocess_check_output = require('lean._util').subprocess_check_output
 
 local lean = {
   mappings = {
-    n = {
-      ['<LocalLeader>i'] = '<Cmd>LeanInfoviewToggle<CR>',
-      ['<LocalLeader>p'] = '<Cmd>LeanInfoviewPinTogglePause<CR>',
-      ['<LocalLeader>x'] = '<Cmd>LeanInfoviewAddPin<CR>',
-      ['<LocalLeader>c'] = '<Cmd>LeanInfoviewClearPins<CR>',
-      ['<LocalLeader>dx'] = '<Cmd>LeanInfoviewSetDiffPin<CR>',
-      ['<LocalLeader>dc'] = '<Cmd>LeanInfoviewClearDiffPin<CR>',
-      ['<LocalLeader>dd'] = '<Cmd>LeanInfoviewToggleAutoDiffPin<CR>',
-      ['<LocalLeader>dt'] = '<Cmd>LeanInfoviewToggleNoClearAutoDiffPin<CR>',
-      ['<LocalLeader>w'] = '<Cmd>LeanInfoviewEnableWidgets<CR>',
-      ['<LocalLeader>W'] = '<Cmd>LeanInfoviewDisableWidgets<CR>',
-      ['<LocalLeader>v'] = '<Cmd>LeanInfoviewViewOptions<CR>',
-      ['<LocalLeader><Tab>'] = '<Cmd>LeanGotoInfoview<CR>',
-      ['<LocalLeader>\\'] = '<Cmd>LeanAbbreviationsReverseLookup<CR>',
+    {
+      '<LocalLeader>i',
+      '<Cmd>LeanInfoviewToggle<CR>',
+      { desc = 'Toggle showing the infoview.' },
+    },
+    {
+      '<LocalLeader>p',
+      '<Cmd>LeanInfoviewPinTogglePause<CR>',
+      { desc = 'Toggle pausing infoview pins.' },
+    },
+    {
+      '<LocalLeader>x',
+      '<Cmd>LeanInfoviewAddPin<CR>',
+      { desc = 'Add an infoview pin.' },
+    },
+    {
+      '<LocalLeader>c',
+      '<Cmd>LeanInfoviewClearPins<CR>',
+      { desc = 'Clear all infoview pins.' },
+    },
+    {
+      '<LocalLeader>dx',
+      '<Cmd>LeanInfoviewSetDiffPin<CR>',
+      { desc = 'Set an infoview diff pin.' },
+    },
+    {
+      '<LocalLeader>dc',
+      '<Cmd>LeanInfoviewClearDiffPin<CR>',
+      { desc = 'Clear all infoview diff pins.' },
+    },
+    {
+      '<LocalLeader>dd',
+      '<Cmd>LeanInfoviewToggleAutoDiffPin<CR>',
+      { desc = 'Toggle "auto-diff" mode in the infoview.' },
+    },
+    {
+      '<LocalLeader>dt',
+      '<Cmd>LeanInfoviewToggleNoClearAutoDiffPin<CR>',
+      { desc = 'Toggle "auto-diff" mode and clear any existing pins.' },
+    },
+    {
+      '<LocalLeader>w',
+      '<Cmd>LeanInfoviewEnableWidgets<CR>',
+      { desc = 'Enable infoview widgets.' },
+    },
+    {
+      '<LocalLeader>W',
+      '<Cmd>LeanInfoviewDisableWidgets<CR>',
+      { desc = 'Disable infoview widgets.' },
+    },
+    {
+      '<LocalLeader>v',
+      '<Cmd>LeanInfoviewViewOptions<CR>',
+      { desc = 'Change the infoview view options.' },
+    },
+    {
+      '<LocalLeader><Tab>',
+      '<Cmd>LeanGotoInfoview<CR>',
+      { desc = 'Jump to the current infoview.' },
+    },
+    {
+      '<LocalLeader>\\',
+      '<Cmd>LeanAbbreviationsReverseLookup<CR>',
+      { desc = 'Show how to type the unicode character under the cursor.' },
     },
-    i = {},
   },
 }
 
@@ -109,11 +158,10 @@ end
 ---Enable mappings for a given buffer
 ---@param bufnr? number the bufnr to enable mappings in, defaulting to 0
 function lean.use_suggested_mappings(bufnr)
-  local opts = { noremap = true, buffer = bufnr or 0 }
-  for mode, mode_mappings in pairs(lean.mappings) do
-    for lhs, rhs in pairs(mode_mappings) do
-      vim.keymap.set(mode, lhs, rhs, opts)
-    end
+  local opts = { buffer = bufnr or 0 }
+  for _, each in ipairs(lean.mappings) do
+    local lhs, rhs, more_opts = unpack(each)
+    vim.keymap.set(each.mode or 'n', lhs, rhs, vim.tbl_extend('error', opts, more_opts))
   end
 end
 

lua/lean/tui.lua

@@ -426,31 +426,30 @@ function BufRenderer:new(obj)
     end,
   })
 
-  local opts = { buffer = obj.buf }
   -- Note that only closures work here, we can't go storing this on vim.b due
   -- to neovim/neovim#12544 wherein the metatable would be lost on retrieval.
   -- In other words, if we do vim.b[..].foo = new_renderer, when we come back
   -- to look at it, it's not a BufRenderer anymore. Surprise!
   vim.keymap.set('n', '<Tab>', function()
     new_renderer:enter_tooltip()
-  end, opts)
+  end, { buffer = obj.buf, desc = 'Enter a tooltip.' })
   vim.keymap.set('n', 'J', function()
     new_renderer:enter_tooltip()
-  end, opts)
+  end, { buffer = obj.buf, desc = 'Enter a tooltip.' })
   vim.keymap.set('n', '<S-Tab>', function()
     new_renderer:goto_parent_tooltip()
-  end, opts)
+  end, { buffer = obj.buf, desc = 'Go to the "parent" tooltip.' })
   vim.keymap.set(
     'n',
     '<LocalLeader>\\',
     require'lean.abbreviations'.show_reverse_lookup,
-    opts
+    { buffer = obj.buf, desc = 'Show how to type the unicode character under the cursor.' }
   )
 
   for key, event in pairs(obj.keymaps or {}) do
     vim.keymap.set('n', key, function()
       new_renderer:event(event)
-    end, opts)
+    end, { buffer = obj.buf, desc = ('Fire a %s event.'):format(event) })
   end
 
   return new_renderer

spec/mappings_spec.lua

@@ -1,13 +1,12 @@
 local infoview = require 'lean.infoview'
-local lean = require 'lean'
 local clean_buffer = require('spec.helpers').clean_buffer
 
 vim.g.lean_config = { mappings = true }
 
 describe('mappings', function()
   describe('for lean buffers', function()
     local any_lean_lhs = '<LocalLeader>i'
-    local rhs = lean.mappings.n[any_lean_lhs]
+    local rhs = '<Cmd>LeanInfoviewToggle<CR>'
 
     it(
       'are bound in lean buffers',
@@ -22,6 +21,19 @@ describe('mappings', function()
       assert.is.empty(vim.fn.maparg(any_lean_lhs, 'n'))
       vim.cmd.bwipeout()
     end)
+
+    it(
+      'all have desc set',
+      clean_buffer(function()
+        local mappings = vim.api.nvim_buf_get_keymap(0, 'nivx')
+        assert.message('unexpectedly empty').is_not_empty(mappings)
+
+        local msg = 'no desc for `%s`:\n%s'
+        for _, each in ipairs(mappings) do
+          assert.message(msg:format(each.lhs, vim.inspect(each))).is_not.empty(each.desc)
+        end
+      end)
+    )
   end)
 
   describe('for infoviews', function()
@@ -36,6 +48,23 @@ describe('mappings', function()
       end)
     )
 
+    it(
+      'all have desc set',
+      clean_buffer(function()
+        infoview.go_to()
+
+        -- TODO: Also check tooltips.
+
+        local mappings = vim.api.nvim_buf_get_keymap(0, 'nivx')
+        assert.message('unexpectedly empty').is_not_empty(mappings)
+
+        local msg = 'no desc for `%s`:\n%s'
+        for _, each in ipairs(mappings) do
+          assert.message(msg:format(each.lhs, vim.inspect(each))).is_not.empty(each.desc)
+        end
+      end)
+    )
+
     it('are not bound in other buffers', function()
       vim.cmd.new()
       assert.is.empty(vim.fn.maparg(any_infoview_lhs, 'n', false, true))

spec/use_suggested_mappings_spec.lua

@@ -6,7 +6,7 @@ describe('mappings', function()
     'are bound in the current buffer and not others',
     clean_buffer(function()
       lean.use_suggested_mappings()
-      assert.is.same(lean.mappings.n['<LocalLeader>i'], vim.fn.maparg('<LocalLeader>i', 'n'))
+      assert.is.same('<Cmd>LeanInfoviewToggle<CR>', vim.fn.maparg('<LocalLeader>i', 'n'))
 
       vim.cmd.new()
       assert.is.empty(vim.fn.maparg('<LocalLeader>i', 'n'))