From df3c5508a39a7dc17fb4a4e16bc9036fb1e07815 Mon Sep 17 00:00:00 2001
From: Patrick Auernig <patrick.auernig@mykolab.com>
Date: Tue, 11 Jun 2024 16:30:00 +0200
Subject: [PATCH] Add descriptions to most key mappings

---
 lua/valeth/keymaps.lua            | 49 +++++++++++++++----------------
 lua/valeth/plugins/dap/ui.lua     | 18 +++++++-----
 lua/valeth/plugins/formatting.lua |  2 +-
 lua/valeth/plugins/harpoon.lua    |  8 ++---
 lua/valeth/plugins/lsp.lua        | 34 ++++++++++++++-------
 lua/valeth/plugins/neogit.lua     |  4 +--
 lua/valeth/plugins/noice.lua      |  2 +-
 lua/valeth/plugins/oil.lua        |  2 +-
 lua/valeth/plugins/telescope.lua  |  6 ++--
 lua/valeth/plugins/trouble.lua    |  2 +-
 10 files changed, 72 insertions(+), 55 deletions(-)

diff --git a/lua/valeth/keymaps.lua b/lua/valeth/keymaps.lua
index f39825b..6bad01b 100644
--- a/lua/valeth/keymaps.lua
+++ b/lua/valeth/keymaps.lua
@@ -1,33 +1,32 @@
-local map = vim.keymap.set
+local maps = {
+    { "n",               "<Leader><CR>", "<cmd>noh<CR>",        { desc = "Clear search highlighting" } },
+    { "n",               "U",            "<cmd>redo<CR>",       { desc = "Redo the last action" } },
+    { "n",               "Y",            "y$",                  { desc = "Yank until the end of the line" } },
+    { { "n", "v", "i" }, "<C-s>",        "<cmd>w<CR>",          { desc = "Write current file" } },
+    { "n",               "s",            "<NOP>" },
 
-map("n", "<Leader><CR>", "<cmd>noh<CR>")
-map("n", "U", "<cmd>redo<CR>")
-map("n", "Y", "y$")
-map({ "n", "v", "i" }, "<C-s>", "<cmd>w<CR>")
-map("n", "s", "<NOP>")
+    -- Yank to clipboard
+    { { "n", "v" },      "<Leader>y",    [["+y]],               { desc = "Yank to clipboard" } },
+    { { "n", "v" },      "<Leader>Y",    [["+Y]],               { desc = "Yank line to clipboard" } },
 
--- Yank to clipboard
-map({ "n", "v" }, "<Leader>y", [["+y]])
-map({ "n", "v" }, "<Leader>Y", [["+Y]])
+    -- Move up and down visual lines for the few times I need wrapping
+    { "n",               "j",            "gj" },
+    { "n",               "k",            "gk" },
 
--- Move up and down visual lines for the few times I need wrapping
-map("n", "j", "gj")
-map("n", "k", "gk")
+    { { "n", "v" },      "H",            "^",                   { desc = "Move to start of line" } },
+    { { "n", "v" },      "L",            "$",                   { desc = "Move to end of line" } },
 
--- More sensible start and end of line
-map({ "n", "v" }, "H", "^")
-map({ "n", "v" }, "L", "$")
+    { "i",               "jk",           "<ESC>l",              { desc = "Exit insert mode", silent = true } },
 
--- Exit insert mode by quickly pressing jk
-map("i", "jk", "<ESC>l", { silent = true })
+    { { "n", "v" },      "<F1>",         "q",                   { desc = "Record a macro" } },
+    { { "n", "v" },      "q",            "<NOP>" },
 
--- This avoids accidentially recording a macro
-map({ "n", "v" }, "<F1>", "q")
-map({ "n", "v" }, "q", "<NOP>")
+    { "v",               "J",            ":move '>+1<CR>gv=gv", { desc = "Move selected lines down" } },
+    { "v",               "K",            ":move '<-2<CR>gv=gv", { desc = "Move selected lines up" } },
 
--- Move selected lines up or down
-map("v", "J", ":move '>+1<CR>gv=gv")
-map("v", "K", ":move '<-2<CR>gv=gv")
+    { "n",               "J",            "mzJ`z",               { desc = "Join lines without moving the cursor" } },
+}
 
--- Join lines without moving the cursor
-map("n", "J", "mzJ`z")
+for _, m in pairs(maps) do
+    vim.keymap.set(m[1], m[2], m[3], m[4])
+end
diff --git a/lua/valeth/plugins/dap/ui.lua b/lua/valeth/plugins/dap/ui.lua
index ce4d1ce..1bf446a 100644
--- a/lua/valeth/plugins/dap/ui.lua
+++ b/lua/valeth/plugins/dap/ui.lua
@@ -8,13 +8,17 @@ spec.dependencies = {
 }
 
 spec.keys = {
-    { "<Leader>dbg", "<cmd>DapContinue<CR>"},
-    { "<Leader>dbr", "<cmd>DapToggleBreakpoint<CR>" },
-    { "<Leader>dso", "<cmd>DapStepOver<CR>" },
-    { "<Leader>dq", "<cmd>DapTerminate<CR>" },
-    { "<Leader>dt", function()
-        require("dapui").toggle()
-    end}
+    { "<Leader>dbg", "<cmd>DapContinue<CR>",         desc = "Continue DAP session" },
+    { "<Leader>dbr", "<cmd>DapToggleBreakpoint<CR>", desc = "Toggle breakpoint" },
+    { "<Leader>dso", "<cmd>DapStepOver<CR>",         desc = "Step over" },
+    { "<Leader>dq",  "<cmd>DapTerminate<CR>",        desc = "Terminate DAP ssession" },
+    {
+        "<Leader>dt",
+        function()
+            require("dapui").toggle()
+        end,
+        desc = "Toggle DAP UI"
+    }
 }
 
 spec.config = function()
diff --git a/lua/valeth/plugins/formatting.lua b/lua/valeth/plugins/formatting.lua
index a68b03f..aaf5702 100644
--- a/lua/valeth/plugins/formatting.lua
+++ b/lua/valeth/plugins/formatting.lua
@@ -28,7 +28,7 @@ local function format_file()
     end
 end
 
-vim.keymap.set("n", "<Leader>fmt", format_file)
+vim.keymap.set("n", "<Leader>fmt", format_file, { desc = "Format the current buffer" })
 
 -- Format on save
 autocmd("BufWritePost", {
diff --git a/lua/valeth/plugins/harpoon.lua b/lua/valeth/plugins/harpoon.lua
index bb06d4c..95d229f 100644
--- a/lua/valeth/plugins/harpoon.lua
+++ b/lua/valeth/plugins/harpoon.lua
@@ -8,7 +8,7 @@ spec.dependencies = {
 }
 
 spec.keys = {
-    { "<Leader>fh", "<cmd>Telescope harpoon marks<CR>" },
+    { "<Leader>fh", "<cmd>Telescope harpoon marks<CR>", desc = "Show harpoon marks" },
 }
 
 spec.config = function()
@@ -19,9 +19,9 @@ spec.config = function()
     local harpoon_mark = require("harpoon.mark")
     local harpoon_ui = require("harpoon.ui")
 
-    vim.keymap.set("n", "<Leader>am", harpoon_mark.add_file)
-    vim.keymap.set("n", "<Leader>gn", harpoon_ui.nav_next)
-    vim.keymap.set("n", "<Leader>gp", harpoon_ui.nav_prev)
+    vim.keymap.set("n", "<Leader>am", harpoon_mark.add_file, { desc = "Add a file to marks" })
+    vim.keymap.set("n", "<Leader>gn", harpoon_ui.nav_next, { desc = "Go to next mark" })
+    vim.keymap.set("n", "<Leader>gp", harpoon_ui.nav_prev, { desc = "Go to previous mark" })
 end
 
 return spec
diff --git a/lua/valeth/plugins/lsp.lua b/lua/valeth/plugins/lsp.lua
index 680dc96..d0758ac 100644
--- a/lua/valeth/plugins/lsp.lua
+++ b/lua/valeth/plugins/lsp.lua
@@ -54,6 +54,21 @@ local function toggle_inlay_hints()
     vim.notify("Inlay hints " .. status, vim.log.levels.INFO)
 end
 
+---@param buf buffer
+---@param mode string | string[]
+---@param rhs string
+---@param lhs string | function
+---@param desc? string
+local function bufmap(buf, mode, rhs, lhs, desc)
+    local opts = {
+        buffer = buf,
+        remap = false,
+        desc = desc
+    }
+
+    vim.keymap.set(mode, rhs, lhs, opts)
+end
+
 spec.config = function()
     local neoconf = require("neoconf")
 
@@ -95,16 +110,15 @@ spec.config = function()
         group = autogroup("LspAttachConfig", {}),
         callback = function(event)
             local tsb = require("telescope.builtin")
-            local opts = { buffer = event.buf, remap = false }
-
-            vim.keymap.set("n", "gd", tsb.lsp_definitions, opts)
-            vim.keymap.set("n", "gr", tsb.lsp_references, opts)
-            vim.keymap.set("n", "K", vim.lsp.buf.hover, opts)
-            vim.keymap.set("n", "<Leader>ca", vim.lsp.buf.code_action, opts)
-            vim.keymap.set("n", "<Leader>ci", vim.diagnostic.open_float, opts)
-            vim.keymap.set("n", "<Leader>re", vim.lsp.buf.rename, opts)
-            vim.keymap.set({ "n", "i" }, "<C-h>", vim.lsp.buf.signature_help, opts)
-            vim.keymap.set("n", "<C-i>", toggle_inlay_hints, opts)
+            local buf = event.buf
+            bufmap(buf, "n", "gd", tsb.lsp_definitions, "Go to definition")
+            bufmap(buf, "n", "gr", tsb.lsp_references, "Go to reference")
+            bufmap(buf, "n", "K", vim.lsp.buf.hover, "Show documentation in hover")
+            bufmap(buf, "n", "<Leader>ca", vim.lsp.buf.code_action, "Run a code action")
+            bufmap(buf, "n", "<Leader>ci", vim.diagnostic.open_float, "Show diagnostics")
+            bufmap(buf, "n", "<Leader>re", vim.lsp.buf.rename, "Rename item under cursor")
+            bufmap(buf, { "n", "i" }, "<C-h>", vim.lsp.buf.signature_help, "Open signature help")
+            bufmap(buf, "n", "<C-i>", toggle_inlay_hints, "Toggle LSP inlay hints")
         end
     })
 
diff --git a/lua/valeth/plugins/neogit.lua b/lua/valeth/plugins/neogit.lua
index 8822d52..a032e92 100644
--- a/lua/valeth/plugins/neogit.lua
+++ b/lua/valeth/plugins/neogit.lua
@@ -7,8 +7,8 @@ spec.dependencies = {
 }
 
 spec.keys = {
-    { "<Leader>vs", "<cmd>Neogit<CR>" },
-    { "<Leader>vc", "<cmd>Neogit commit<CR>" },
+    { "<Leader>vs", "<cmd>Neogit<CR>", desc = "Open NeoGit" },
+    { "<Leader>vc", "<cmd>Neogit commit<CR>", desc = "Open NeoGit commit" },
 }
 
 spec.config = true
diff --git a/lua/valeth/plugins/noice.lua b/lua/valeth/plugins/noice.lua
index a84cbc3..9b67b73 100644
--- a/lua/valeth/plugins/noice.lua
+++ b/lua/valeth/plugins/noice.lua
@@ -19,7 +19,7 @@ spec.opts = {
 }
 
 spec.keys = {
-    { "<leader>nd", "<cmd>NoiceDismiss<CR>" },
+    { "<leader>nd", "<cmd>NoiceDismiss<CR>", desc = "Dismiss all noice messages"},
 }
 
 spec.dependencies = {
diff --git a/lua/valeth/plugins/oil.lua b/lua/valeth/plugins/oil.lua
index 5cb2277..34ebaea 100644
--- a/lua/valeth/plugins/oil.lua
+++ b/lua/valeth/plugins/oil.lua
@@ -71,7 +71,7 @@ spec.lazy = false
 spec.cmd = { "Oil" }
 
 spec.keys = {
-    { "<Leader>ft", "<cmd>Oil<CR>", mode = "n" }
+    { "<Leader>ft", "<cmd>Oil<CR>", mode = "n", desc = "Open oil file table" }
 }
 
 return spec
diff --git a/lua/valeth/plugins/telescope.lua b/lua/valeth/plugins/telescope.lua
index e5afd87..bcc8642 100644
--- a/lua/valeth/plugins/telescope.lua
+++ b/lua/valeth/plugins/telescope.lua
@@ -9,9 +9,9 @@ spec.dependencies = {
 }
 
 spec.keys = {
-    { "<Leader>ff", "<cmd>Telescope find_files<CR>" },
-    { "<Leader>fb", "<cmd>Telescope buffers<CR>" },
-    { "<Leader>fg", "<cmd>Telescope live_grep<CR>" },
+    { "<Leader>ff", "<cmd>Telescope find_files<CR>", desc = "Find in files" },
+    { "<Leader>fb", "<cmd>Telescope buffers<CR>",    desc = "Find in buffers" },
+    { "<Leader>fg", "<cmd>Telescope live_grep<CR>",  desc = "Find by grepping" },
 }
 
 spec.config = function()
diff --git a/lua/valeth/plugins/trouble.lua b/lua/valeth/plugins/trouble.lua
index 6132b0c..f3eb3da 100644
--- a/lua/valeth/plugins/trouble.lua
+++ b/lua/valeth/plugins/trouble.lua
@@ -7,7 +7,7 @@ spec.dependencies = {
 }
 
 spec.keys = {
-    { "<Leader>ct", "<cmd>TroubleToggle<CR>" },
+    { "<Leader>ct", "<cmd>TroubleToggle<CR>", desc = "Toggle trouble window" },
 }
 
 return spec