[neovim] Various items:

- Restructure the config
- Add nvim-surround
- Add which-key window border
- Comments as documentation
- Tweak GitSigns blame color to swerve away from CursorLine

neovim/init.lua

@@ -37,7 +37,7 @@ vim.g.netrw_winsize = 25 -- width of the file explorer
 vim.g.netrw_liststyle = 3 -- tree style listing
 
 -- Escape exits terminal mode
-vim.keymap.set("t", "<Esc>", "<c-\\><c-n>", { noremap = true })
+-- vim.keymap.set("t", "<Esc>", "<c-\\><c-n>", { noremap = true })
 
 -- Sane vim split naviagation (via Gaslight blog)
 vim.keymap.set("n", "<c-j>", "<c-w>j", { noremap = true })
@@ -49,10 +49,24 @@ vim.keymap.set("t", "<c-k>", "<c-\\><c-n><c-w>k", { noremap = true })
 vim.keymap.set("t", "<c-h>", "<c-\\><c-n><c-w>h", { noremap = true })
 vim.keymap.set("t", "<c-l>", "<c-\\><c-n><c-w>l", { noremap = true })
 
-vim.keymap.set({"i", "n", "t", "v"}, "<F10>", function () vim.cmd("nohlsearch") end)
+vim.keymap.set(
+  {"i", "n", "t", "v"},
+  "<F10>",
+  function ()
+    vim.cmd("nohlsearch")
+  end,
+  { desc = ":nohlsearch" }
+)
 
--- Wrap the function body in an if statement to verify existence of idelayout
-vim.keymap.set({"n", "t"}, "<leader>z", function () vim.cmd("exec idelayout") end)
+vim.keymap.set(
+  {"n", "t"},
+  "<leader>z",
+  function ()
+    -- TODO: Wrap the function body in an if statement to verify existence of idelayout
+    vim.cmd("exec idelayout")
+  end,
+  { desc = "Revert window layout" }
+)
 
 -- lazy.nvim
 local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
@@ -78,6 +92,30 @@ require("lazy").setup({
       vim.cmd.colorscheme("dracula")
     end,
   },
+  {
+    "kylechui/nvim-surround",
+    version = "*", -- Use for stability; omit to use `main` branch for the latest features
+    event = "VeryLazy",
+    config = function()
+        require("nvim-surround").setup({
+            -- Configuration here, or leave empty to use defaults
+        })
+    end
+  },
+  {
+    "folke/which-key.nvim",
+    event = "VeryLazy",
+    init = function()
+      vim.o.timeout = true
+      -- N.B. Setting `timeoutlen` to 0 seems to break the plugin
+      vim.o.timeoutlen = 300 -- 0? 500? 300?
+    end,
+    opts = {
+      window = {
+        border = "shadow",
+      },
+    },
+  },
   "williamboman/mason.nvim",
   "williamboman/mason-lspconfig.nvim",
   "nvimdev/lspsaga.nvim",
@@ -97,20 +135,20 @@ require("lazy").setup({
   "hrsh7th/cmp-nvim-lsp-signature-help",
   "tpope/vim-fugitive",
   "lewis6991/gitsigns.nvim",
-  "tpope/vim-surround",
-  {
-    "folke/which-key.nvim",
-    event = "VeryLazy",
-    init = function()
-      vim.o.timeout = true
-      vim.o.timeoutlen = 300
-    end,
-  }
 })
 
+--[[ mason
+Mason manages external editor plugins such as LSP servers, DAP servers,
+linters, and formatters. There are further recommended plugins for better
+integration.
+--]]
 require('mason').setup()
 require('mason-lspconfig').setup()
 
+--[[ lualine
+Lualine provides the status bar as well as the tabline. Not sure whether
+it also provides the buffer breadcrumbs.
+--]]
 require('lualine').setup {
   options = { theme = 'dracula' },
   tabline = {
@@ -118,42 +156,20 @@ require('lualine').setup {
   }
 }
 
+--[[ Telescope
+Telescope provides lists, pickers, etc. This section includes just the
+functions bound to keymaps.
+--]]
 local builtin = require('telescope.builtin')
 vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = 'Telescope: find files' })
 vim.keymap.set('n', '<leader>fg', builtin.live_grep, { desc = 'Telescope: live grep' })
 vim.keymap.set('n', '<leader>fb', builtin.buffers, { desc = 'Telescope: buffers' })
 vim.keymap.set('n', '<leader>fh', builtin.help_tags, { desc = 'Telescope: help tags' })
 
---------------------
--- nvim-lspconfig --
---------------------
+--[[ nvim-cmp
+nvim-cmp is a text completion engine.
+]]
 
--- Setup language servers.
-local lua_ls_setup = {
-    settings = {
-      Lua = {
-        runtime = {
-            -- Tell the language server which version of Lua you're using (most likely LuaJIT in the case of Neovim)
-            version = "LuaJIT",
-        },
-        diagnostics = {
-            -- Get the language server to recognize the `vim` global
-            globals = { "vim" },
-        },
-        workspace = {
-            -- Make the server aware of Neovim runtime files
-            library = vim.api.nvim_get_runtime_file("", true),
-            checkThirdParty = false,
-        },
-        -- Do not send telemetry data containing a randomized but unique identifier
-        telemetry = {
-            enable = false,
-        },
-      },
-    },
-}
-
--- Set up nvim-cmp.
 local cmp = require'cmp'
 
 cmp.setup({
@@ -215,6 +231,34 @@ cmp.setup.cmdline(':', {
   })
 })
 
+--[[ nvim-lspconfig
+--]]
+
+-- Setup language servers.
+local lua_ls_setup = {
+    settings = {
+      Lua = {
+        runtime = {
+            -- Tell the language server which version of Lua you're using (most likely LuaJIT in the case of Neovim)
+            version = "LuaJIT",
+        },
+        diagnostics = {
+            -- Get the language server to recognize the `vim` global
+            globals = { "vim" },
+        },
+        workspace = {
+            -- Make the server aware of Neovim runtime files
+            library = vim.api.nvim_get_runtime_file("", true),
+            checkThirdParty = false,
+        },
+        -- Do not send telemetry data containing a randomized but unique identifier
+        telemetry = {
+            enable = false,
+        },
+      },
+    },
+}
+
 local capabilities = require('cmp_nvim_lsp').default_capabilities()
 
 local lspconfig = require('lspconfig')
@@ -355,6 +399,9 @@ require('gitsigns').setup({
 
 require('lspsaga').setup()
 
+-- Tweak GitSigns blame color
+vim.cmd("highlight GitSignsCurrentLineBlame gui=bold guifg=#339944")
+
 -- Switch syntax highlighting on
 vim.cmd("syntax enable")