Added more documentation comments

26 files changed, 34 insertions, 0 deletions

diff --git a/modules/desktop/default.nix b/modules/desktop/default.nix
index 5926913..18dc6a4 100644
--- a/modules/desktop/default.nix
+++ b/modules/desktop/default.nix
@@ -4,6 +4,7 @@
   ...
 }:
 
+# Desktop - Desktop environment configuration (i3, GTK, polybar)
 {
   imports = [
     ./i3
diff --git a/modules/desktop/gtk/default.nix b/modules/desktop/gtk/default.nix
index 4b89d3d..af33196 100644
--- a/modules/desktop/gtk/default.nix
+++ b/modules/desktop/gtk/default.nix
@@ -5,6 +5,7 @@
   ...
 }:
 
+# GTK - GTK3/GTK4 theme configuration (Nightfox dark theme)
 {
   config = lib.mkIf config.desktop.enable {
     gtk = {
diff --git a/modules/desktop/i3/default.nix b/modules/desktop/i3/default.nix
index fa51ab9..ed29e91 100644
--- a/modules/desktop/i3/default.nix
+++ b/modules/desktop/i3/default.nix
@@ -5,6 +5,7 @@
   ...
 }:
 
+# i3 - Window manager configuration (gaps, colors, startup, keybindings)
 {
   config = lib.mkIf config.desktop.enable {
     xsession.windowManager.i3 = {
diff --git a/modules/desktop/i3/keybindings.nix b/modules/desktop/i3/keybindings.nix
index 9d6e668..6933979 100644
--- a/modules/desktop/i3/keybindings.nix
+++ b/modules/desktop/i3/keybindings.nix
@@ -4,6 +4,7 @@
   config,
 }:
 
+# Keybindings - i3 keyboard shortcuts (app launchers, vim directions, workspaces)
 let
   mod = "Mod4";
 in
diff --git a/modules/desktop/polybar/bar/default.nix b/modules/desktop/polybar/bar/default.nix
index ce6db3b..44498c3 100644
--- a/modules/desktop/polybar/bar/default.nix
+++ b/modules/desktop/polybar/bar/default.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Bar - Polybar bar definitions (main bar)
 {
   "bar/main" = import ./main.nix { inherit config; };
 }
diff --git a/modules/desktop/polybar/bar/main.nix b/modules/desktop/polybar/bar/main.nix
index e05d9b4..93edf90 100644
--- a/modules/desktop/polybar/bar/main.nix
+++ b/modules/desktop/polybar/bar/main.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Main - Main polybar bar configuration (dimensions, colors, modules)
 with config.scheme.withHashtag;
 let
   largerFontSize = toString (builtins.ceil (config.fonts.size * 9.0 / 8.0));
diff --git a/modules/desktop/polybar/default.nix b/modules/desktop/polybar/default.nix
index a07c0c6..c52377c 100644
--- a/modules/desktop/polybar/default.nix
+++ b/modules/desktop/polybar/default.nix
@@ -5,6 +5,7 @@
   ...
 }:
 
+# Polybar - Status bar configuration (i3 integration, modules)
 {
   config = lib.mkIf config.desktop.enable {
     services.polybar.enable = true;
diff --git a/modules/desktop/polybar/module/battery.nix b/modules/desktop/polybar/module/battery.nix
index dc9e6f4..d392e16 100644
--- a/modules/desktop/polybar/module/battery.nix
+++ b/modules/desktop/polybar/module/battery.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Battery - Battery status module with icons and charging animation
 with config.scheme.withHashtag;
 {
   type = "internal/battery";
diff --git a/modules/desktop/polybar/module/cpu.nix b/modules/desktop/polybar/module/cpu.nix
index 64d5b47..9d5b859 100644
--- a/modules/desktop/polybar/module/cpu.nix
+++ b/modules/desktop/polybar/module/cpu.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# CPU - CPU usage percentage module
 with config.scheme.withHashtag;
 {
   type = "internal/cpu";
diff --git a/modules/desktop/polybar/module/date.nix b/modules/desktop/polybar/module/date.nix
index 0e432e9..7a9e1ca 100644
--- a/modules/desktop/polybar/module/date.nix
+++ b/modules/desktop/polybar/module/date.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Date - Current date display module
 with config.scheme.withHashtag;
 {
   type = "internal/date";
diff --git a/modules/desktop/polybar/module/default.nix b/modules/desktop/polybar/module/default.nix
index 2295ac6..1ccbd02 100644
--- a/modules/desktop/polybar/module/default.nix
+++ b/modules/desktop/polybar/module/default.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Module - Polybar module definitions (battery, cpu, date, i3, memory, volume, wifi, etc.)
 {
   "module/battery" = import ./battery.nix { inherit config; };
   "module/cpu" = import ./cpu.nix { inherit config; };
diff --git a/modules/desktop/polybar/module/ethernet-separator.nix b/modules/desktop/polybar/module/ethernet-separator.nix
index 2c2a738..cfdf9e4 100644
--- a/modules/desktop/polybar/module/ethernet-separator.nix
+++ b/modules/desktop/polybar/module/ethernet-separator.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Ethernet-separator - Visual separator for ethernet module
 with config.scheme.withHashtag;
 {
   type = "internal/network";
diff --git a/modules/desktop/polybar/module/ethernet.nix b/modules/desktop/polybar/module/ethernet.nix
index 28c7a1b..72f8e0c 100644
--- a/modules/desktop/polybar/module/ethernet.nix
+++ b/modules/desktop/polybar/module/ethernet.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Ethernet - Wired network module (connection speed)
 with config.scheme.withHashtag;
 {
   type = "internal/network";
diff --git a/modules/desktop/polybar/module/i3.nix b/modules/desktop/polybar/module/i3.nix
index 8565d41..f910b80 100644
--- a/modules/desktop/polybar/module/i3.nix
+++ b/modules/desktop/polybar/module/i3.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# i3 - i3 workspace display module (focused, occupied, urgent workspaces)
 with config.scheme.withHashtag;
 {
   type = "internal/i3";
diff --git a/modules/desktop/polybar/module/memory.nix b/modules/desktop/polybar/module/memory.nix
index 7f8de0a..d032377 100644
--- a/modules/desktop/polybar/module/memory.nix
+++ b/modules/desktop/polybar/module/memory.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Memory - RAM usage module (displays GB used)
 with config.scheme.withHashtag;
 {
   type = "internal/memory";
diff --git a/modules/desktop/polybar/module/separator.nix b/modules/desktop/polybar/module/separator.nix
index 0a75a30..23b52b9 100644
--- a/modules/desktop/polybar/module/separator.nix
+++ b/modules/desktop/polybar/module/separator.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Separator - Visual separator between modules
 with config.scheme.withHashtag;
 {
   type = "custom/text";
diff --git a/modules/desktop/polybar/module/time.nix b/modules/desktop/polybar/module/time.nix
index 6fe921d..e8dae08 100644
--- a/modules/desktop/polybar/module/time.nix
+++ b/modules/desktop/polybar/module/time.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Time - Current time display module (12-hour format)
 with config.scheme.withHashtag;
 {
   type = "internal/date";
diff --git a/modules/desktop/polybar/module/volume.nix b/modules/desktop/polybar/module/volume.nix
index eacd53d..1d1352a 100644
--- a/modules/desktop/polybar/module/volume.nix
+++ b/modules/desktop/polybar/module/volume.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# Volume - PulseAudio volume level module with icons
 with config.scheme.withHashtag;
 {
   type = "internal/pulseaudio";
diff --git a/modules/desktop/polybar/module/wifi-separator.nix b/modules/desktop/polybar/module/wifi-separator.nix
index 2527b68..6bb42cb 100644
--- a/modules/desktop/polybar/module/wifi-separator.nix
+++ b/modules/desktop/polybar/module/wifi-separator.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# WiFi-separator - Visual separator for WiFi module
 with config.scheme.withHashtag;
 {
   type = "internal/network";
diff --git a/modules/desktop/polybar/module/wifi.nix b/modules/desktop/polybar/module/wifi.nix
index 5a4d17f..6ee848f 100644
--- a/modules/desktop/polybar/module/wifi.nix
+++ b/modules/desktop/polybar/module/wifi.nix
@@ -1,5 +1,6 @@
 { config }:
 
+# WiFi - Wireless network module (signal strength, speed)
 with config.scheme.withHashtag;
 {
   type = "internal/network";
diff --git a/modules/desktop/polybar/module/xwindow.nix b/modules/desktop/polybar/module/xwindow.nix
index fd73a6b..79c0f95 100644
--- a/modules/desktop/polybar/module/xwindow.nix
+++ b/modules/desktop/polybar/module/xwindow.nix
@@ -1,5 +1,6 @@
 { }:
 
+# XWindow - Focused window title module
 {
   type = "internal/xwindow";
   label = "%title:0:20:...%";
diff --git a/modules/fonts/default.nix b/modules/fonts/default.nix
index 110bd1d..3f6cade 100644
--- a/modules/fonts/default.nix
+++ b/modules/fonts/default.nix
@@ -5,6 +5,7 @@
   ...
 }:
 
+# Fonts - Font configuration (Fira Code Nerd Font)
 {
   options.fonts = {
     normal = lib.mkOption {
diff --git a/modules/scripts/deep-clean.sh b/modules/scripts/deep-clean.sh
index dcbd62b..5d1c87a 100644
--- a/modules/scripts/deep-clean.sh
+++ b/modules/scripts/deep-clean.sh
@@ -1,3 +1,6 @@
+# Deep clean script for Nix systems
+# Removes old generations, garbage, and optimizes store
+# WARNING: Do NOT run with sudo - run as normal user
 echo "--- Starting Nix Deep Clean ---"
 
 if [[ $EUID -eq 0 ]]; then
diff --git a/modules/scripts/default.nix b/modules/scripts/default.nix
index ca555c7..3fea3df 100644
--- a/modules/scripts/default.nix
+++ b/modules/scripts/default.nix
@@ -4,6 +4,7 @@
   ...
 }:
 
+# Scripts - Home directory shell scripts (deep-clean, screen-recording, system-monitor)
 {
   config = {
     home.sessionPath = [
diff --git a/modules/scripts/screen-recording.sh b/modules/scripts/screen-recording.sh
index a3bf86a..c0e8525 100644
--- a/modules/scripts/screen-recording.sh
+++ b/modules/scripts/screen-recording.sh
@@ -1,3 +1,7 @@
+# Screen recording script using FFmpeg and slop for region selection
+# Records X11 screen to MP4 with x264 encoding
+# Usage: screen-recording.sh [-s|--select]
+#   -s, --select  Launch slop to select recording region
 OUT_DIR="$HOME/Videos/Recordings"
 mkdir -p "$OUT_DIR"
 
diff --git a/modules/scripts/system-monitor.sh b/modules/scripts/system-monitor.sh
index 951428c..cadae3a 100644
--- a/modules/scripts/system-monitor.sh
+++ b/modules/scripts/system-monitor.sh
@@ -1,3 +1,7 @@
+# System monitor script using tmux to run bottom and nvtop side-by-side
+# Opens a tmux session with:
+#   - Left pane: bottom (system/process monitor)
+#   - Right pane: nvtop (GPU monitor)
 SESSION="system-monitor"
 
 kitty @ set-font-size -- -4