config/linux-dev/nvim/init.lua

@@ -1,4 +1,22 @@
-require('config.options')
-require('config.keymaps')
-require('config.lazy')
+--[[
+  Neovim Lua config: ways to set things
+
+  - vim.opt : preferred modern API for options (handles lists, cleaner syntax)
+  - vim.g   : global variables (leader key, plugin settings, disable builtins, etc.)
+  - vim.o   : global-only option (rarely needed directly)
+  - vim.wo  : window-local option (applies to current window only, use in autocmds)
+  - vim.bo  : buffer-local option (applies to current buffer only, use in autocmds)
+  - vim.env : set environment variables (like PATH, LANG)
+  - vim.fn  : call Vimscript functions (e.g. vim.fn.getcwd())
+  - vim.cmd : run raw Vimscript/Ex commands (e.g. vim.cmd("colorscheme desert"))
+  - vim.api : low-level Neovim API (create autocmds, keymaps, buffer/window ops, etc.)
+
+  TL;DR -> use vim.opt + vim.g in options.lua for defaults.
+           Use vim.wo/vim.bo only in context-specific tweaks (autocmds).
+           Use vim.env, vim.fn, vim.cmd, vim.api as needed for scripting.
+]]
+
+require("config.options")
+require("config.keymaps")
+require("config.lazy")
 require("config.autocmds")

config/linux-dev/nvim/lua/config/autocmds.lua

@@ -29,16 +29,18 @@ end, { desc = "Reload the current colorscheme" })
 
 ----------------------------------------------
 
--- Command `:TSHighlightRoots` (works but uncomment only when used)
--- Description:
---   Collects all Tree-sitter highlight groups, resolves their links,
---   and outputs the unique root groups actually used (for theming/debugging).
---
--- Usage:
---   :TSHighlightRoots              → prints roots in the command line
---   :TSHighlightRoots <filename>   → writes roots into <filename> (overwrites)
---     (filename supports `~` and tab-completion)
---
+--[[
+Command :TSHighlightRoots (works but uncomment only when used)
+
+Description:
+  Collects all Tree-sitter highlight groups, resolves their links,
+  and outputs the unique root groups actually used (for theming/debugging).
+
+Usage:
+  :TSHighlightRoots              -> prints roots in the command line
+  :TSHighlightRoots <filename>   -> writes roots into <filename> (overwrites)
+    (filename supports ~ and tab-completion)
+]]
 -- local function resolve_link(name)
 -- 	local seen = {}
 -- 	while name and not seen[name] do
@@ -88,7 +90,6 @@ end, { desc = "Reload the current colorscheme" })
 -- 	end,
 -- })
 
-----------------------------------------------
 ----------------------------------------------
 -- Useful tricks that do not fully work
 ----------------------------------------------

config/linux-dev/nvim/lua/config/options.lua

@@ -40,8 +40,7 @@ vim.opt.mouse = "a"
 
 -- Full path on status line
 vim.opt.statusline = "%= %F%m%r%h%w ─ (%l,%c %P) %="
-vim.opt.fillchars:append({ stl = '─', stlnc = '─' })
-
+vim.opt.fillchars:append({ stl = "─", stlnc = "─" })
 
 -- Sync clipboard between OS and Neovim
 vim.schedule(function()