📝 Add docstrings to master

scripts/assets/executable_insults.zsh

@@ -1,3 +1,4 @@
+# insult prints a random insult message formatted in yellow; if INSULTS_OFFENSIVE_ENABLED is set, additional offensive insults are included.
 function insult() {
 	local INSULTS=(
 		"You type like I drive.",
@@ -1169,4 +1170,4 @@ function compliment() {
 
 alias insult_cow='insult | cowthink'
 alias excuse_cow='excuse | cowthink'
-alias compliment_cow='compliment | cowthink'
+alias compliment_cow='compliment | cowthink'

scripts/assets/executable_utils.zsh

@@ -23,7 +23,8 @@ WHITE_BRIGHT="\e[97m"
 
 # Enhanced utility functions with better error handling and status reporting
 
-# Status reporting functions (enhanced versions of existing color codes)
+# print_status prints a colorized, emoji-prefixed status line to stdout.
+# print_status accepts two arguments: the first is the status type (one of: error, warning, success, info, step, title) which selects color and emoji, and the second is the message string to display.
 print_status() {
     local status=$1
     local message=$2
@@ -53,7 +54,8 @@ print_status() {
     esac
 }
 
-# Safe command execution with error handling
+# safe_execute runs a shell command and prints an error message on failure, returning the command's exit code.
+# Takes the command to run as the first argument and an optional error message as the second argument; on failure the provided message is printed (with the exit code) and that exit code is returned.
 safe_execute() {
     local command="$1"
     local error_msg="${2:-Command failed}"
@@ -67,21 +69,23 @@ safe_execute() {
     fi
 }
 
-# Check if command exists
+# command_exists checks whether the given command name is available in PATH.
 command_exists() {
     command -v "$1" >/dev/null 2>&1
 }
 
-# Platform detection
+# is_macos checks whether the current platform is macOS.
 is_macos() {
     [[ "$OSTYPE" == "darwin"* ]]
 }
 
+# is_linux checks whether the current platform is Linux.
+# Exits with status 0 if OSTYPE starts with "linux-gnu", 1 otherwise.
 is_linux() {
     [[ "$OSTYPE" == "linux-gnu"* ]]
 }
 
-# Array utilities
+# array_contains checks whether a specified element is present in an array and returns 0 if found, 1 otherwise.
 array_contains() {
     local array="$1[@]"
     local seeking=$2
@@ -95,12 +99,13 @@ array_contains() {
     return $in
 }
 
-# Enhanced version of silent_background with better error handling
+# silent_background runs a command detached from the terminal in the background while keeping its stderr visible to the caller.
+# It temporarily adjusts job control to start the command, redirects the command's stderr to the caller's stderr, disowns the job, and then restores job control.
 silent_background() {
     set +m && { "$@" 2>&3 & disown; pid=$!; } 3>&2 2>/dev/null && set -m
 }
 
-# Error handling utility
+# handle_error prints an error message for the most recently executed command if it failed and returns that command's exit code.
 handle_error() {
     local exit_code=$?
     local command="$1"
@@ -111,6 +116,7 @@ handle_error() {
     return 0
 }
 
+# zsh_stats displays Zsh history statistics, showing the most-used commands with counts and usage percentages.
 function zsh_stats() {
   echo -e "${CYAN_BRIGHT}  == Zsh history statistics == ${RESET}"
   HISTFILE=~/.zsh_history fc -R
@@ -274,4 +280,4 @@ if [[ $OSTYPE == 'linux'* ]]; then
   export FORGIT_COPY_CMD='xclip -selection clipboard'
 fi
 
-zinit snippet OMZ::lib/history.zsh
+zinit snippet OMZ::lib/history.zsh

scripts/assets/font_install.zsh

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 
 # Optimized font installation for dotfiles
-# This script handles nerd font installation for Linux systems
+# install_nerd_fonts downloads and installs missing Nerd Font variants and Noto Color Emoji into ~/.local/share/fonts.
+# It extracts ZIP archives when `unzip` is available, removes Windows-compatible variants, refreshes the font cache with `fc-cache` when present, and skips fonts that are already installed.
 
 install_nerd_fonts() {
     local nerd_font='https://github.com/ryanoasis/nerd-fonts/releases/download/v2.3.3'
@@ -71,4 +72,4 @@ install_nerd_fonts() {
     else
         print_status success "All nerd fonts already installed."
     fi
-}
+}

scripts/assets/zsh_bindings.zsh

@@ -1,7 +1,7 @@
 # Zsh key bindings and completion configuration
 # This file contains fzf-tab and completion settings
 
-# Zsh Vi Mode configuration
+# zvm_config configures zsh-vi-mode by setting the terminal type and cursor styles for insertion, normal, and append modes.
 zvm_config() {
   # Always identify as xterm-256color to zsh-vi-mode plugin
   ZVM_TERM=xterm-256color
@@ -10,7 +10,7 @@ zvm_config() {
   ZVM_OPPEND_MODE_CURSOR=$ZVM_CURSOR_UNDERLINE
 }
 
-# Zsh Vi Mode after init
+# zvm_after_init configures zsh completion, integrates zoxide and fzf/fzf-tab previews, applies extensive zstyle rules for git, processes, files, env vars, and tools, and finally loads fast-syntax-highlighting and autosuggestions.
 zvm_after_init() {
   zicompinit
   [ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
@@ -124,4 +124,4 @@ zvm_after_init() {
 
 # Load zsh-vi-mode
 zinit ice depth=1
-zinit light jeffreytse/zsh-vi-mode
+zinit light jeffreytse/zsh-vi-mode

scripts/assets/zsh_prompt.zsh

@@ -37,6 +37,10 @@ function @yazpt_segment_nl() {
   fi
 }
 
+# @yazpt_segment_excuse constructs an excuse message when the last command exited with a relevant non-zero code and stores it in yazpt_state[excuse].
+#
+# When INSULTS_ENABLED is true and the recorded exit code is not 0, 127, or 130, the function builds a message
+# that begins with a bomb emoji, includes the output of excuse(), and ends with a newline; otherwise it stores an empty string.
 function @yazpt_segment_excuse() {
   local code="$yazpt_state[exit_code]"
   local excuse_msg=''
@@ -56,6 +60,7 @@ APP_CHEERS_PATTERNS=(
   "git_ship"
 )
 
+# @yazpt_segment_cheers appends a celebratory message to yazpt_state[cheers] when cheers are enabled, the last command exited successfully, and LAST_COMMAND matches any pattern in APP_CHEERS_PATTERNS; on macOS with iTerm2 integration it also triggers an iTerm2 fireworks action.
 function @yazpt_segment_cheers() {
   local do_cheers=false
   local cheers_msg=''
@@ -83,9 +88,11 @@ function @yazpt_segment_cheers() {
   yazpt_state[cheers]=$cheers_msg
 }
 
-# Configure yazpt
+# configure_yazpt configures default yazpt prompt settings.
+# It initializes YAZPT_LAYOUT from PROMPT_LAYOUT, sets YAZPT_CWD_COLOR to 6 (cyan),
+# and sets YAZPT_EXECTIME_MIN_SECONDS to 1.
 function configure_yazpt {
   YAZPT_LAYOUT=$PROMPT_LAYOUT
   YAZPT_CWD_COLOR=6 # cyan
   YAZPT_EXECTIME_MIN_SECONDS=1
-}
+}

scripts/bin/executable_autoupdate.zsh

@@ -3,7 +3,7 @@
 # check whether this script is being eval'ed
 [[ $0 =~ "autoupdate.zsh" ]] && sourced=0 || sourced=1
 
-# Track errors from various update commands in an array and show the result before exiting
+# update_error appends a descriptive error entry to the global update_errors array when a command's exit code is non-zero.
 function update_error() {
 	error_cmd=$1
 	error_code=$2
@@ -15,6 +15,7 @@ function update_error() {
 
 tp='success'
 
+# show_errors prints any accumulated update errors, sends a terminal notification when the script is sourced, and otherwise exits with status 0 if overall status is "success" or 1 if "error".
 function show_errors() {
 	if [ ${#update_errors[@]} -ne 0 ]; then
 		tp='error'
@@ -35,6 +36,7 @@ function show_errors() {
 	fi
 }
 
+# check_interval computes the number of seconds since the timestamp stored in ~/FILENAME and echoes the interval; if the file does not exist it treats the last update as 0.
 function check_interval() {
 	now=$(date +%s)
 	if [ -f ~/${1} ]; then
@@ -46,6 +48,7 @@ function check_interval() {
 	echo ${interval}
 }
 
+# revolver_stop stops the revolver progress display and restores the terminal cursor visibility.
 function revolver_stop() {
   revolver stop
   tput cnorm
@@ -175,4 +178,4 @@ unset tp
 unset -f update_error
 unset -f check_interval
 unset -f show_errors
-unset -f revolver_stop
+unset -f revolver_stop

scripts/bin/executable_lint.zsh

@@ -14,7 +14,7 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# Function to print colored output
+# print_status prints a colored status message based on the given status type ('error', 'warning', 'success', 'info'); the second argument is the message to display.
 print_status() {
     local status_type=$1
     local message=$2
@@ -191,4 +191,4 @@ else
     exit 1
 fi
 
-print_status info "Linting complete!"
+print_status info "Linting complete!"

scripts/bin/executable_validate_security.zsh

@@ -13,7 +13,7 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
-# Function to print colored output
+# print_status prints a message prefixed with a status icon and colored according to the status type ('error', 'warning', 'success', or other).
 print_status() {
     local status_type=$1
     local message=$2
@@ -142,4 +142,4 @@ echo "3. Use 'set -e' for proper error handling"
 echo "4. Avoid dynamic eval and sudo when possible"
 echo "5. Store secrets in environment variables or secure vaults"
 echo "6. Regularly audit and update dependencies"
-echo "7. Use proper ignore patterns to avoid committing sensitive files"
+echo "7. Use proper ignore patterns to avoid committing sensitive files"