From c1cdc96b8c2837a5a93b1898250f2ba8a8179bef Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 27 Oct 2025 01:18:28 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`master`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @neopilotai. * https://github.com/neopilotai/dotfiles/pull/1#issuecomment-3449139024 The following files were modified: * `scripts/assets/executable_insults.zsh` * `scripts/assets/executable_utils.zsh` * `scripts/assets/font_install.zsh` * `scripts/assets/zsh_bindings.zsh` * `scripts/assets/zsh_prompt.zsh` * `scripts/bin/executable_autoupdate.zsh` * `scripts/bin/executable_lint.zsh` * `scripts/bin/executable_validate_security.zsh` --- scripts/assets/executable_insults.zsh | 3 ++- scripts/assets/executable_utils.zsh | 22 +++++++++++++------- scripts/assets/font_install.zsh | 5 +++-- scripts/assets/zsh_bindings.zsh | 6 +++--- scripts/assets/zsh_prompt.zsh | 11 ++++++++-- scripts/bin/executable_autoupdate.zsh | 7 +++++-- scripts/bin/executable_lint.zsh | 4 ++-- scripts/bin/executable_validate_security.zsh | 4 ++-- 8 files changed, 40 insertions(+), 22 deletions(-) diff --git a/scripts/assets/executable_insults.zsh b/scripts/assets/executable_insults.zsh index 3ce4a8ed765..c0d86b1b474 100644 --- a/scripts/assets/executable_insults.zsh +++ b/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' \ No newline at end of file diff --git a/scripts/assets/executable_utils.zsh b/scripts/assets/executable_utils.zsh index d224ee4851b..e3f6ac82416 100644 --- a/scripts/assets/executable_utils.zsh +++ b/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 \ No newline at end of file diff --git a/scripts/assets/font_install.zsh b/scripts/assets/font_install.zsh index a44a2e43086..e6574fd0fd6 100644 --- a/scripts/assets/font_install.zsh +++ b/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 -} +} \ No newline at end of file diff --git a/scripts/assets/zsh_bindings.zsh b/scripts/assets/zsh_bindings.zsh index 9b3ca69ca1d..33fdc803cfd 100644 --- a/scripts/assets/zsh_bindings.zsh +++ b/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 \ No newline at end of file diff --git a/scripts/assets/zsh_prompt.zsh b/scripts/assets/zsh_prompt.zsh index f7a09928b80..7a27e6d2080 100644 --- a/scripts/assets/zsh_prompt.zsh +++ b/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 -} +} \ No newline at end of file diff --git a/scripts/bin/executable_autoupdate.zsh b/scripts/bin/executable_autoupdate.zsh index 5b5a9c04d27..ac6629fafb3 100644 --- a/scripts/bin/executable_autoupdate.zsh +++ b/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 \ No newline at end of file diff --git a/scripts/bin/executable_lint.zsh b/scripts/bin/executable_lint.zsh index 35e031b874e..bbfc12475b3 100644 --- a/scripts/bin/executable_lint.zsh +++ b/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!" \ No newline at end of file diff --git a/scripts/bin/executable_validate_security.zsh b/scripts/bin/executable_validate_security.zsh index 1c42ec167ef..75acc301daf 100644 --- a/scripts/bin/executable_validate_security.zsh +++ b/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" \ No newline at end of file