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(),