From 355f142751f4eb049cbd958876d45da5e5e51402 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A9ana=20=E6=B1=9F?= <leana.jiang+git@icloud.com>
Date: Wed, 9 Jul 2025 10:51:52 +0200
Subject: [PATCH] nvim/maps: document bindings

---
 .config/nvim/lua/maps.lua | 79 +++++++++++++++++++++------------------
 1 file changed, 43 insertions(+), 36 deletions(-)

diff --git a/.config/nvim/lua/maps.lua b/.config/nvim/lua/maps.lua
index 8caccdd3..d4afb0f9 100644
--- a/.config/nvim/lua/maps.lua
+++ b/.config/nvim/lua/maps.lua
@@ -1,49 +1,56 @@
 vim.g.mapleader = " "
 vim.g.maplocalleader = " "
 
--- Move
-vim.keymap.set("v", "J", ":m '>+1<CR>gv")
-vim.keymap.set("v", "K", ":m '<-2<CR>gv")
-vim.keymap.set("v", ">", ">gv")
-vim.keymap.set("v", "<", "<gv")
-vim.keymap.set("v", "=", "=gv")
+---@param bind string
+---@param cmd function | string
+---@param desc string
+---@param userargs? table
+local vnoremap = function(bind, cmd, desc, userargs)
+    local args = userargs or {}
+    args.desc = desc
+    vim.keymap.set("v", bind, cmd, args)
+end
 
--- Centered motions
-vim.keymap.set("n", "<C-d>", "<C-d>zz")
-vim.keymap.set("n", "<C-u>", "<C-u>zz")
-vim.keymap.set("n", "gd", "gdzz")
-vim.keymap.set("n", "gD", "<C-w>vgd", { remap = true })
-vim.keymap.set("n", "``", "``zz")
-vim.keymap.set("n", "n", "nzzzv")
-vim.keymap.set("n", "N", "Nzzzv")
-vim.keymap.set("n", "J", "mzJ`z")
+---@param bind string
+---@param cmd function | string
+---@param desc string
+---@param userargs? table
+local nnoremap = function(bind, cmd, desc, userargs)
+    local args = userargs or {}
+    args.desc = desc
+    vim.keymap.set("n", bind, cmd, args)
+end
+
+-- Move
+vnoremap("J", ":m '>+1<CR>gv", "Move line down")
+vnoremap("K", ":m '<-2<CR>gv", "Move line up")
+vnoremap(">", ">gv", "Shift right (keep selection)")
+vnoremap("<", "<gv", "Shift left (keep selection)")
+
+nnoremap("<C-d>", "<C-d>zz", "Page down (then center)")
+nnoremap("<C-u>", "<C-u>zz", "Page up (then center)")
+nnoremap("gd", "gdzz", "Go to definition (then center)")
+nnoremap("gD", "<C-w>vgd", "Go to definition in a new window", { remap = true })
+nnoremap("``", "``zz", "Jump to `` (then center)")
+nnoremap("J", "mzJ`z", "Join line (and restore cursor)")
 
 -- Better clipboard
-vim.keymap.set({ "n", "x", "v" }, "<leader>d", '"_d')
-vim.keymap.set({ "n", "x", "v" }, "<leader>c", '"_dc')
-vim.keymap.set({ "n", "x", "v" }, "<leader>p", '"_dP')
-vim.keymap.set({ "n", "x", "v" }, "<leader>y", '"+y')
-
--- Linewrap jk
--- Only use gj et al. when needed
-vim.keymap.set("n", "k", "v:count == 0 ? 'gk' : 'k'", { expr = true, silent = true })
-vim.keymap.set("n", "j", "v:count == 0 ? 'gj' : 'j'", { expr = true, silent = true })
+vim.keymap.set({ "n", "x", "v" }, "<leader>d", '"_d', { desc = "Delete (void register)" })
+vim.keymap.set({ "n", "x", "v" }, "<leader>c", '"_dc', { desc = "Change (void regsiter)" })
+vim.keymap.set({ "n", "x", "v" }, "<leader>p", '"_dP', { desc = "Paste (void register)" })
+vim.keymap.set({ "n", "x", "v" }, "<leader>y", '"+y', { desc = "Yank (system clipboard)" })
 
 -- Replace selected token
-vim.keymap.set("n", "<leader>pv", function() vim.cmd("Oil") end) -- Project View
-vim.keymap.set("n", "<leader>nf", function() vim.cmd("enew") end) -- New File
-vim.keymap.set("n", "<leader>so", function() vim.cmd("so %") end) -- Source buffer
-vim.keymap.set("c", "#capl", [[\(.\{-}\)]]) -- helpers in regex
-vim.keymap.set("c", "#capm", [[\(.*\)]])
-vim.keymap.set("n", "<leader>+x", function() vim.cmd("!chmod +x %") end) -- Permission
-vim.keymap.set("n", "<leader>-x", function() vim.cmd("!chmod -x %") end)
-vim.keymap.set("n", "<leader>hg", function() vim.cmd("Inspect") end) -- Highlight Group
-vim.keymap.set("n", "Q", "<nop>") -- *do not* repeat the last recorded register [count] times.
+nnoremap("<leader>pv", function() vim.cmd("Oil") end, "Open oil")
+nnoremap("leader>+x", ":!chmod +x %", "Make executable")
+nnoremap("leader>-x", ":!chmod -x %", "Make non-executable")
+vim.keymap.set("c", "#capl", [[\(.\{-}\)]], { desc = "Capture more" })
+vim.keymap.set("c", "#capm", [[\(.*\)]], { desc = "Capture less" })
 
 -- Diagnostics
-vim.keymap.set("n", "<leader>e", vim.diagnostic.open_float)
-vim.keymap.set("n", "<leader>pe", function() vim.diagnostic.jump { count = -1, float = true } end)
-vim.keymap.set("n", "<leader>ne", function() vim.diagnostic.jump { count = 1, float = true } end)
+nnoremap("<leader>e", vim.diagnostic.open_float, "Open diagnostic as float")
+nnoremap("<leader>pe", function() vim.diagnostic.jump { count = -1, float = true } end, "Previous diagnostic")
+nnoremap("<leader>ne", function() vim.diagnostic.jump { count = 1, float = true } end, "Next diagnostic")
 
 -- Resize window using shift + arrow keys
 -- Credit: github.com/GrizzlT