docs: Add documentational comments

tools/nvim/init.lua

@@ -6,6 +6,7 @@
 @Description neovim 配置文件
 ]]
 
+-- Entry point of neovim configuration
 require("config.options")
 require("config.plugins")
 require("config.colorscheme")

tools/nvim/lazy-lock.json

@@ -1,7 +1,7 @@
 {
   "LuaSnip": { "branch": "master", "commit": "c9b9a22904c97d0eb69ccb9bab76037838326817" },
   "alpha-nvim": { "branch": "main", "commit": "de72250e054e5e691b9736ee30db72c65d560771" },
-  "auto-session": { "branch": "main", "commit": "021b64ed7d4ac68a37be3ad28d8e1cba5bec582c" },
+  "auto-session": { "branch": "main", "commit": "16016db7f79d942a1538eaafb15a39f033f7a359" },
   "betterTerm.nvim": { "branch": "main", "commit": "5d3f41d9e8b3553d49764906a14e45a08dbe2308" },
   "bufferline.nvim": { "branch": "main", "commit": "655133c3b4c3e5e05ec549b9f8cc2894ac6f51b3" },
   "catppuccin": { "branch": "main", "commit": "f67b886d65a029f12ffa298701fb8f1efd89295d" },
@@ -16,7 +16,7 @@
   "flash.nvim": { "branch": "main", "commit": "34c7be146a91fec3555c33fe89c7d643f6ef5cf1" },
   "friendly-snippets": { "branch": "main", "commit": "efff286dd74c22f731cdec26a70b46e5b203c619" },
   "gitsigns.nvim": { "branch": "main", "commit": "d8918f06624dd53b9a82bd0e29c31bcfd541b40d" },
-  "grug-far.nvim": { "branch": "main", "commit": "635e69adf3a714621bd0a289314bc23c5848babb" },
+  "grug-far.nvim": { "branch": "main", "commit": "82a81e0b5638667893d0d89f232dbb510cc5ab14" },
   "hover.nvim": { "branch": "main", "commit": "140c4d0ae9397b76baa46b87c574f5377de09309" },
   "kanagawa.nvim": { "branch": "master", "commit": "988082eb00b845e4afbcaa4fd8e903da8a3ab3b9" },
   "lazy.nvim": { "branch": "main", "commit": "d8f26efd456190241afd1b0f5235fe6fdba13d4a" },
@@ -28,10 +28,10 @@
   "mason.nvim": { "branch": "main", "commit": "e2f7f9044ec30067bc11800a9e266664b88cda22" },
   "mini.pairs": { "branch": "main", "commit": "7e834c5937d95364cc1740e20d673afe2d034cdb" },
   "nvim-cmp": { "branch": "main", "commit": "12509903a5723a876abd65953109f926f4634c30" },
-  "nvim-lspconfig": { "branch": "master", "commit": "e5bf88e5ea1c4cea5ea96b1e970cb264f7a401a1" },
+  "nvim-lspconfig": { "branch": "master", "commit": "1f941b3668151963fca3e1230922c433ea4b7b64" },
   "nvim-surround": { "branch": "main", "commit": "ae298105122c87bbe0a36b1ad20b06d417c0433e" },
   "nvim-tree.lua": { "branch": "master", "commit": "d529a99f88e0dff02e0aa275db2f595cd252a2c8" },
-  "nvim-treesitter": { "branch": "master", "commit": "d34e62afd3e483fe0fa2f24b6323f3bb1d35ddcc" },
+  "nvim-treesitter": { "branch": "master", "commit": "2206739829518c9ea59dbdb9003e0147fdaf2d1c" },
   "nvim-treesitter-context": { "branch": "master", "commit": "bece284c5322ddf6946fa4bdc383a2bc033269d7" },
   "nvim-web-devicons": { "branch": "master", "commit": "1c9136332840edee0c593f2f4f89598c8ed97f5f" },
   "obsidian.nvim": { "branch": "main", "commit": "ae1f76a75c7ce36866e1d9342a8f6f5b9c2caf9b" },

tools/nvim/lua/config/colors.lua

@@ -1,3 +1,4 @@
+-- This file *currently* contains the colorscheme for lualine (status line)
 local colors = {
   bg = "#202328",
   fg = "#bbc2cf",

tools/nvim/lua/config/colorscheme.lua

@@ -1 +1,2 @@
+-- Change the colorscheme here, use SPACE u i or :Telescope colorscheme to change colorscheme
 vim.cmd.colorscheme("catppuccin-mocha")

tools/nvim/lua/config/diagnostics.lua

@@ -1,5 +1,6 @@
 local signs = require("config.icons").diagnostics
 
+-- This provides the diagnostics signs near the line numbers
 for type, icon in pairs(signs) do
   local hl = "DiagnosticSign" .. type
   vim.fn.sign_define(hl, { text = icon, texthl = hl, numhl = "" })

tools/nvim/lua/config/icons.lua

@@ -1,3 +1,6 @@
+-- icons.lua
+-- All icons used in the configuration are defined in this file.
+-- Currently are only used in diagnostics, lualine, gitsigns
 local M = {
   diagnostics = {
     Error = "",

tools/nvim/lua/config/keymaps.lua

@@ -1 +1,2 @@
+-- Entry point of keymaps configuration
 require("keymaps")

tools/nvim/lua/config/options.lua

@@ -1,22 +1,25 @@
 -- <leader> is space
 vim.g.mapleader = " "
 vim.g.maplocalleader = "\\"
--- Disable netrw
+-- Disable netrw (file explorer) use NvimTree instead
 vim.g.loaded_netrw = 1
 vim.g.loaded_netrwPlugin = 1
 -- Disable Perl
 vim.g.loaded_perl_provider = 0 -- Don't load Perl
 
+-- Format on save
 vim.g.autoformat = true
 
 local opt = vim.opt
 
 -- Clipboard
+-- `unnamedplus` for system clipboard
 opt.clipboard = vim.env.SSH_TTY and "" or "unnamedplus"
 -- Line number
 opt.number = true
 opt.relativenumber = true
 
+-- Confirm before dangerous operations
 opt.confirm = true
 
 -- Word wrap
@@ -32,26 +35,30 @@ opt.shiftround = true
 opt.ignorecase = true
 opt.smartcase = true
 
+-- Highlight current line
 opt.cursorline = true
+-- opt.cursorcolumn = true -- Highlight current column
 -- Terminal GUI
 opt.termguicolors = true
 
--- Fold
+--- Fold
 opt.foldmethod = "expr"
+-- Folding provided by treesitter
 opt.foldexpr = "nvim_treesitter#foldexpr()"
 opt.foldlevel = 99
 opt.foldlevelstart = 1
 
--- Statusline
+-- Disable status line: Use `lualine` instead
 opt.laststatus = 0
 
 -- Hide Command Line if empty
 opt.cmdheight = 0
 
 -- Scroll
-opt.scrolloff = 5
-opt.sidescrolloff = 10
+opt.scrolloff = 5      -- Always show 5 lines above/below cursor
+opt.sidescrolloff = 10 -- Always show 10 columns left/right of cursor
 
+-- Conceal: Hide some characters, might be useful for markdown and LaTeX
 opt.conceallevel = 2
 
 vim.o.sessionoptions = "blank,buffers,curdir,folds,help,tabpages,winsize,winpos,terminal,localoptions"

tools/nvim/lua/config/plugins.lua

@@ -1 +1,2 @@
+-- Entry point for all plugins
 require("plugins")

tools/nvim/lua/config/servers.lua

@@ -2,33 +2,37 @@
 --- Check https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md
 --- for available server and name
 local M = {}
+-- Ensure that the following servers are installed and set
+-- Use :Mason to list all available servers
 M.servers = {
   "ast_grep",
-  "bashls", -- Bash
-  "clangd", -- C/C++
-  "cssls", -- CSS
-  "denols", -- Deno
+  "bashls",         -- Bash
+  "clangd",         -- C/C++
+  "cssls",          -- CSS
+  "denols",         -- Deno
   -- "cmake",                   -- CMake
-  "eslint", -- JavaScript
-  "gopls", -- Go
-  "hls", -- Haskell
-  "html", -- HTML
-  "jsonls", -- JSON
-  "lua_ls", -- Lua
+  "eslint",         -- JavaScript
+  "gopls",          -- Go
+  "hls",            -- Haskell
+  "html",           -- HTML
+  "jsonls",         -- JSON
+  "lua_ls",         -- Lua
   "markdown_oxide", -- Markdown
-  "omnisharp", -- C# & F#
-  "powershell_es", -- PowerShell
-  "pyright", -- Python
-  "rust_analyzer", -- Rust
-  "svelte", -- Svelte
-  "svlangserver", -- SystemVerilog
-  "tailwindcss", -- TailwindCSS
-  "taplo", -- TOML
-  "ts_ls", -- TypeScript
-  "vimls", -- vimscript
-  "yamlls", -- YAML
+  "omnisharp",      -- C# & F#
+  "powershell_es",  -- PowerShell
+  "pyright",        -- Python
+  "rust_analyzer",  -- Rust
+  "svelte",         -- Svelte
+  "svlangserver",   -- SystemVerilog
+  "tailwindcss",    -- TailwindCSS
+  "taplo",          -- TOML
+  "ts_ls",          -- TypeScript
+  "vimls",          -- vimscript
+  "yamlls",         -- YAML
 }
 
+
+-- Configuration for each server defines here
 M.server_config = {
   lua_ls = {
     capabilities = vim.lsp.protocol.make_client_capabilities(),

tools/nvim/lua/keymaps/visual-multi.lua

@@ -1,4 +1,7 @@
+-- Note that this plugin is a fork for colemak
+-- Use mouse to select multiple cursors
 vim.g.VM_mouse_mappings = 1
+-- Disable default mappings
 vim.g.VM_default_mappings = 0
 vim.g.VM_custom_motions = {
   -- https://github.com/mg979/vim-visual-multi/issues/93

tools/nvim/lua/plugins/appearance.lua

@@ -1,16 +1,18 @@
 return {
-  { "catppuccin/nvim", name = "catppuccin" },
+  -- Colorschemes
+  { "catppuccin/nvim",          name = "catppuccin" },
   { "olimorris/onedarkpro.nvim" },
   { "rebelot/kanagawa.nvim" },
+  -- Highlight objects under the cursor
   { "RRethy/vim-illuminate" },
-  {
+  { -- Modern Status Line
     "nvim-lualine/lualine.nvim",
     dependencies = { "nvim-tree/nvim-web-devicons" },
     config = function()
       require("plugins.mod.lualine")
     end,
   },
-  {
+  { -- Highlight yanked text
     "gbprod/yanky.nvim",
     config = function()
       require("yanky").setup({
@@ -22,10 +24,10 @@ return {
       })
     end,
   },
-  { import = "plugins.mod.alpha-nvim" },
-  { import = "plugins.mod.winbar-nvim" },
-  { import = "plugins.mod.bufferline" },
-  {
+  { import = "plugins.mod.alpha-nvim" },  -- Dashboard
+  { import = "plugins.mod.winbar-nvim" }, -- Breadcrumb
+  { import = "plugins.mod.bufferline" },  -- Buffer Top Bar
+  {                                       -- Git Blames, Changes
     "lewis6991/gitsigns.nvim",
     config = function()
       require("gitsigns").setup({
@@ -33,7 +35,7 @@ return {
       })
     end,
   },
-  {
+  { -- Highlight and navigate between TODOs
     "folke/todo-comments.nvim",
     dependencies = { "nvim-lua/plenary.nvim" },
     opts = {},