docs: Add documentational comments

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 = {},