style(comments): reflow and clarify script comments

Rewrap long comments throughout transcode.sh for more consistent line
length and readability. Clarify a few explanatory comments around
filesize formatting, preset descriptions, empty input handling, ffprobe
probing, temporary output creation, and output verification.

No runtime behavior is changed.

1 files changed, 38 insertions, 32 deletions

diff --git a/transcode.sh b/transcode.sh
index ce0be24..129ba88 100755
--- a/transcode.sh
+++ b/transcode.sh
@@ -76,9 +76,9 @@ fi
 # SHELL SCRIPT HARDENING
 #
 # This script enables strict and predictable behavior for improved safety,
-# security, and debuggability. These measures help avoid common pitfalls
-# such as accidental globbing, unexpected alias expansion, silent failures,
-# or unintended word splitting.
+# security, and debuggability. These measures help avoid common pitfalls such
+# as accidental globbing, unexpected alias expansion, silent failures, or
+# unintended word splitting.
 ###############################################################################
 
 # Unalias everything to avoid unexpected alias expansion
@@ -103,9 +103,9 @@ set -o pipefail
 ###############################################################################
 # SCRIPT METADATA
 #
-# These variables describe the script and are used for the --version output
-# and for informational messages. They are marked readonly to prevent
-# accidental modification at runtime.
+# These variables describe the script and are used for the --version output and
+# for informational messages. They are marked readonly to prevent accidental
+# modification at runtime.
 ###############################################################################
 readonly SCRIPTNAME=${0##*/}
 readonly DESCRIPTION="Batch transcode helper for media files using ffmpeg."
@@ -154,8 +154,8 @@ CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/config.toml"
 # Kept for deprecation warning only — no longer read for codec data.
 readonly SKIP_CODECS_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/transcode.sh/skip.conf"
 
-# Sentinel flags: set to 1 by the CLI option parser so that load_config()
-# knows which values have already been provided and must not be overridden.
+# Sentinel flags: set to 1 by the CLI option parser so that load_config() knows
+# which values have already been provided and must not be overridden.
 _CLI_CONFIG_FILE=0
 _CLI_CONTINUE=0
 _CLI_HWACCEL=0
@@ -373,8 +373,8 @@ resolve_path() {
   readlink -f -- "$1" 2>/dev/null || realpath -- "$1"
 }
 
-# Format a byte count into a human-readable IEC size. Uses numfmt so values are
-# displayed with binary units such as K, M, G, etc.
+# Format a byte count into a human-readable IEC size.
+# Uses numfmt so values are displayed with binary units such as K, M, G, etc.
 format_filesize() {
   numfmt --to=iec -- "$1"
 }
@@ -383,13 +383,13 @@ format_filesize() {
 # TERMINAL COLOR SETUP
 #
 # Colors and style escape sequences are configured dynamically through the
-# `setup_colors` function, which enables or disables color output based on
-# the value of ENABLE_COLOR. When enabled, terminal capabilities are detected
-# via `tput`, falling back to ANSI escapes if unavailable.
+# `setup_colors` function, which enables or disables color output based on the
+# value of ENABLE_COLOR. When enabled, terminal capabilities are detected via
+# `tput`, falling back to ANSI escapes if unavailable.
 #
-# This script respects the NO_COLOR standard (https://no-color.org/).
-# If the environment variable NO_COLOR is set (to any value), all color output
-# is disabled. If FORCE_COLOR is set, colors are always enabled.
+# This script respects the NO_COLOR standard (https://no-color.org/). If the
+# environment variable NO_COLOR is set (to any value), all color output is
+# disabled. If FORCE_COLOR is set, colors are always enabled.
 ###############################################################################
 
 # NOTE: This block calls debug() and reads $DEBUG. Both must be defined before
@@ -454,15 +454,15 @@ setup_colors
 ###############################################################################
 # CONFIGURATION FILE
 #
-# Load defaults from config.toml if it exists. Values are only applied when
-# the corresponding CLI flag has NOT already been set (CLI takes precedence).
+# Load defaults from config.toml if it exists. Values are only applied when the
+# corresponding CLI flag has NOT already been set (CLI takes precedence).
 # Requires tomlq when config.toml is present.
 ###############################################################################
 
 # Query a single scalar value from config.toml via tomlq.
 # Usage: _tomlq_get <key>   (e.g. ".encoding.preset")
-# Outputs the raw string on stdout; returns non-zero if the key is absent
-# or tomlq fails for any reason.
+# Outputs the raw string on stdout; returns non-zero if the key is absent or
+# tomlq fails for any reason.
 _tomlq_get() {
   tomlq -r "$1" "$CONFIG_FILE" 2>/dev/null
 }
@@ -691,8 +691,8 @@ load_preset() {
     exit $EXIT_CONFIG_ERROR
   }
 
-  # Reject preset files that are world-writable to prevent arbitrary users
-  # from injecting shell code.
+  # Reject preset files that are world-writable to prevent arbitrary users from
+  # injecting shell code.
   #
   # Symlinks must be resolved first: stat on a symlink returns the permissions
   # of the symlink itself (always 777 on Linux), not the target. We use
@@ -727,7 +727,8 @@ load_preset() {
 # List all presets in PRESET_DIR, printing their name and optional description.
 #
 # A description is read from the first line of the preset file only.
-# If that line matches:  # description: <text>
+# If that line matches:
+# # description: <text>
 # (case-insensitive, leading whitespace ignored) the text is extracted;
 # otherwise the preset is listed without a description.
 #
@@ -1112,7 +1113,8 @@ calculate_saved_percentage() {
 }
 
 # Append one row to the size report TSV, creating the header when needed.
-# Empty byte/percentage fields are allowed for failures where no output size exists.
+# Empty byte/percentage fields are allowed for failures where no output size
+# exists.
 append_size_report_row() {
   [[ $SIZE_REPORT -eq 1 && $DRY_RUN -eq 0 ]] || return $EXIT_OK
 
@@ -1195,6 +1197,8 @@ encode_one() {
   local current_file_index="$2"
   local amount_total_files="$3"
 
+  # Ignore empty input entries so callers can safely pass filtered file lists
+  # without treating blank lines as errors.
   if [[ -z "$input_file" ]]; then
     return $EXIT_OK
   fi
@@ -1210,12 +1214,14 @@ encode_one() {
   fi
 
   msg "Processing [$current_file_index/$amount_total_files]:" "$input_file"
+
   if [[ ! -f "$input_file" ]]; then
     ((_REPORT_ENCODING_FAILED++))
     append_size_report_row "failed" "$filename"
     error "Not found:" "$input_file"
     return $EXIT_RUNTIME_FAILURE
   fi
+
   if [[ ! -r "$input_file" ]]; then
     ((_REPORT_ENCODING_FAILED++))
     append_size_report_row "failed" "$filename"
@@ -1223,8 +1229,8 @@ encode_one() {
     return $EXIT_RUNTIME_FAILURE
   fi
 
-  # Probe codec and pixel format in a single ffprobe invocation to halve
-  # the startup overhead on large batches.
+  # Probe codec, pixel format and frame rate in a single ffprobe invocation to
+  # decrease the startup overhead on large batches.
   local probe_out
   probe_out=$(ffprobe -v error -select_streams v:0 \
     -show_entries stream=codec_name,pix_fmt,r_frame_rate \
@@ -1334,9 +1340,9 @@ encode_one() {
   directory=$(dirname -- "$input_file")
 
   # Temp file is created in the same directory as the input so that `mv` is
-  # atomic on the same filesystem (avoid cross-device rename issues).
-  # mktemp provides cryptographically random names and atomic creation,
-  # unlike $$.$RANDOM which has limited entropy and is predictable.
+  # atomic on the same filesystem (avoid cross-device rename issues). mktemp
+  # provides cryptographically random names and atomic creation, unlike
+  # $$.$RANDOM which has limited entropy and is predictable.
   temporary_output_file=$(mktemp -- "$directory/.${stem}_${PRESET_NAME}.XXXXXX${extension:+.$extension}")
   TEMPORARY_FILES+=("$temporary_output_file")
   debug "Temporary output path:" "$temporary_output_file"
@@ -1385,9 +1391,9 @@ encode_one() {
     # Integrity verification: confirm the encoded output is a valid, playable
     # file before discarding the original. ffprobe exits non-zero and emits
     # nothing useful if the container is corrupt or contains no readable
-    # streams, so we treat any non-zero exit as a fatal encode failure.
-    # Skip with --no-verify-output when trust in the encoder is high and the
-    # extra probe round-trip is undesirable.
+    # streams, so we treat any non-zero exit as a fatal encode failure. Skip
+    # with --no-verify-output when trust in the encoder is high and the extra
+    # probe round-trip is undesirable.
     if [[ $VERIFY_OUTPUT -eq 1 ]]; then
       debug "Verifying output integrity:" "$temporary_output_file"
       if ! ffprobe -v error "file:$temporary_output_file" >/dev/null 2>&1; then