chore: added + fixed all description comments in all scripts

18 files changed, 27 insertions, 12 deletions

diff --git a/modules/communication/neomutt/neomutt-sync.sh b/modules/communication/neomutt/neomutt-sync.sh
index d0dac63..67e007d 100644
--- a/modules/communication/neomutt/neomutt-sync.sh
+++ b/modules/communication/neomutt/neomutt-sync.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Sync mail with mbsync and index new messages with notmuch,
+# showing progress via a dialog gauge.
+
 DIALOGRC=$(mktemp)
 NOTMUCH_LOG=$(mktemp)
 TITLE="[󰇮  SYNCING MAIL]"
diff --git a/modules/desktop/eww/bar/niri-status.lua b/modules/desktop/eww/bar/niri-status.lua
index e4f21a2..fdf88d2 100644
--- a/modules/desktop/eww/bar/niri-status.lua
+++ b/modules/desktop/eww/bar/niri-status.lua
@@ -1,5 +1,5 @@
 #!/usr/bin/env luajit
--- niri-status: emit {workspaces: [...], active_windows: [...]} as one JSON
+-- Emit {workspaces: [...], active_windows: [...]} as one JSON
 -- object per line, driven by a single niri event-stream subscription.
 --
 -- This replaces the old activate-windows.lua + workspaces.lua pair. Those
diff --git a/modules/desktop/eww/bar/system-stats.lua b/modules/desktop/eww/bar/system-stats.lua
index c7ee4fb..bc9cc90 100644
--- a/modules/desktop/eww/bar/system-stats.lua
+++ b/modules/desktop/eww/bar/system-stats.lua
@@ -1,5 +1,5 @@
 #!/usr/bin/env luajit
--- system-stats: emit {cpu, ram, net, sound} as JSON.
+-- Emit {cpu, ram, net, sound} as JSON.
 --
 -- Single-threaded LuaJIT port of the original Python script. Instead of
 -- OS threads, a single supervisor loop schedules the periodic cpu/ram and
diff --git a/modules/file-management/yazi/file-chooser.sh b/modules/file-management/yazi/file-chooser.sh
index 7978222..788a5d9 100644
--- a/modules/file-management/yazi/file-chooser.sh
+++ b/modules/file-management/yazi/file-chooser.sh
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Launch yazi as a file/directory chooser and write the result to an output file.
+
 # $1 toggles multiple selection
 # $2 toggles directory select mode
 # $3 toggles save file mode
diff --git a/modules/media/screen-recording/screen-recording.sh b/modules/media/screen-recording/screen-recording.sh
index f4e65ab..90cbc85 100644
--- a/modules/media/screen-recording/screen-recording.sh
+++ b/modules/media/screen-recording/screen-recording.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Record the screen with wf-recorder into ~/Videos/Recordings,
+# optionally selecting a region to capture with slurp.
+
 OUT_DIR="$HOME/Videos/Recordings"
 mkdir -p "$OUT_DIR"
 
diff --git a/modules/media/screen-recording/screen-recording.zsh b/modules/media/screen-recording/screen-recording.zsh
index 835ec43..2f2baa3 100644
--- a/modules/media/screen-recording/screen-recording.zsh
+++ b/modules/media/screen-recording/screen-recording.zsh
@@ -1,4 +1,5 @@
 #compdef screen-recording
+# Zsh completion for the screen-recording command.
 
 _arguments \
   '(-s --select)'{-s,--select}'[Launch slurp to select recording region]'
diff --git a/modules/networking/usque/usque-warp.sh b/modules/networking/usque/usque-warp.sh
index 9d0f6e1..700c857 100644
--- a/modules/networking/usque/usque-warp.sh
+++ b/modules/networking/usque/usque-warp.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Manage a Cloudflare WARP (usque) tunnel: connect, disconnect,
+# or report Waybar status.
+
 set -euo pipefail
 
 info()  { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
diff --git a/modules/networking/usque/usque-warp.zsh b/modules/networking/usque/usque-warp.zsh
index fbb340e..0227486 100644
--- a/modules/networking/usque/usque-warp.zsh
+++ b/modules/networking/usque/usque-warp.zsh
@@ -1,4 +1,5 @@
 #compdef usque-warp
+# Zsh completion for the usque-warp command.
 
 _arguments \
   '1: :->cmds' \
diff --git a/modules/office/calcurse/calcurse-sync.sh b/modules/office/calcurse/calcurse-sync.sh
index 9165f67..fafbc6e 100644
--- a/modules/office/calcurse/calcurse-sync.sh
+++ b/modules/office/calcurse/calcurse-sync.sh
@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-#
 # Keeps calcurse's data directory in git, so you can back it up / sync
 # it across machines via a remote (e.g. a private GitHub repo).
 #
diff --git a/modules/security/gopass/gopass-sync-init.sh b/modules/security/gopass/gopass-sync-init.sh
index e00ce73..5d5e423 100644
--- a/modules/security/gopass/gopass-sync-init.sh
+++ b/modules/security/gopass/gopass-sync-init.sh
@@ -1,7 +1,4 @@
 #!/usr/bin/env bash
-
-# gopass-sync-init
-#
 # Prepare the gopass password store directory for git-backed syncing.
 #
 # This runs during home-manager activation. It ensures the store directory
diff --git a/modules/security/gpg/gpg-backup.sh b/modules/security/gpg/gpg-backup.sh
index c1b6c25..685c4a3 100644
--- a/modules/security/gpg/gpg-backup.sh
+++ b/modules/security/gpg/gpg-backup.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Export all GPG keys and revocation certificates to an encrypted backup
+# file, or decrypt and import them back from one.
+
 set -euo pipefail
 
 info()  { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
diff --git a/modules/security/gpg/gpg-backup.zsh b/modules/security/gpg/gpg-backup.zsh
index f47bbe8..c229acb 100644
--- a/modules/security/gpg/gpg-backup.zsh
+++ b/modules/security/gpg/gpg-backup.zsh
@@ -1,4 +1,5 @@
 #compdef gpg-backup
+# Zsh completion for the gpg-backup command.
 
 _arguments \
   '1: :->cmds' \
diff --git a/modules/security/ssh/gpg-ssh-key-load.sh b/modules/security/ssh/gpg-ssh-key-load.sh
index d662dbe..02dda1d 100644
--- a/modules/security/ssh/gpg-ssh-key-load.sh
+++ b/modules/security/ssh/gpg-ssh-key-load.sh
@@ -1,7 +1,4 @@
 #!/usr/bin/env bash
-
-# gpg-ssh-key-load
-#
 # Load the SSH key stored in gopass into the gpg-agent.
 #
 # SSH keys are served by gpg-agent (enable-ssh-support): the private key at
diff --git a/modules/system/deep-clean/deep-clean.sh b/modules/system/deep-clean/deep-clean.sh
index d698bfd..f22a620 100644
--- a/modules/system/deep-clean/deep-clean.sh
+++ b/modules/system/deep-clean/deep-clean.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Remove old NixOS, home-manager and user profile generations, then run
+# a full garbage collection and store optimisation.
+
 set -euo pipefail
 
 info()  { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
diff --git a/modules/system/nix-update/nix-update.sh b/modules/system/nix-update/nix-update.sh
index bacfc20..e65a33c 100644
--- a/modules/system/nix-update/nix-update.sh
+++ b/modules/system/nix-update/nix-update.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Update and switch the home-manager and/or NixOS configurations.
 
 set -euo pipefail
 
diff --git a/modules/system/nix-update/nix-update.zsh b/modules/system/nix-update/nix-update.zsh
index a9500e6..a0d23e3 100644
--- a/modules/system/nix-update/nix-update.zsh
+++ b/modules/system/nix-update/nix-update.zsh
@@ -1,4 +1,5 @@
 #compdef nix-update
+# Zsh completion for the nix-update command.
 
 _arguments \
   '1: :->target' \
diff --git a/modules/web/chromium/extensions/inject_extension_key.lua b/modules/web/chromium/extensions/inject_extension_key.lua
index 30ed318..41c631d 100644
--- a/modules/web/chromium/extensions/inject_extension_key.lua
+++ b/modules/web/chromium/extensions/inject_extension_key.lua
@@ -1,6 +1,6 @@
 #!/usr/bin/env luajit
--- inject_extension_key: strip JSON comments and trailing commas from a
--- manifest, inject the extension's public key, and rewrite it.
+-- Strip JSON comments and trailing commas from a manifest, inject the
+-- extension's public key, and rewrite it.
 local dkjson = require("dkjson")
 
 local manifest_path = assert(arg[1], "usage: inject_extension_key.lua <manifest> <ext_key>")
diff --git a/modules/web/chromium/patch_native_host.lua b/modules/web/chromium/patch_native_host.lua
index d8abebb..df2365f 100644
--- a/modules/web/chromium/patch_native_host.lua
+++ b/modules/web/chromium/patch_native_host.lua
@@ -1,5 +1,5 @@
 #!/usr/bin/env luajit
--- patch_native_host: set allowed_origins in a native messaging host manifest.
+-- Set allowed_origins in a native messaging host manifest.
 local dkjson = require("dkjson")
 
 local extension_id = assert(arg[1], "usage: patch_native_host.lua <extension_id> <input> <output>")