📝 Add docstrings to general-improvements-and-typo-fixes

Docstrings generation was requested by @RoseSecurity.

* #980 (comment)

The following files were modified:

* `rootfs/etc/profile.d/aws.sh`
* `rootfs/etc/profile.d/fzf.sh`
* `rootfs/etc/profile.d/prompt.sh`
* `rootfs/templates/wrapper-body.sh`

Author: coderabbitai[bot]

rootfs/etc/profile.d/aws.sh

@@ -7,6 +7,7 @@ export AWS_REGION_ABBREVIATION_TYPE=${AWS_REGION_ABBREVIATION_TYPE:-fixed}
 export AWS_DEFAULT_SHORT_REGION=${AWS_DEFAULT_SHORT_REGION:-$(aws-region --"${AWS_REGION_ABBREVIATION_TYPE}" "${AWS_DEFAULT_REGION:-us-west-2}")}
 export GEODESIC_AWS_HOME
 
+# _aws_config_home locates or creates the AWS configuration directory, exports GEODESIC_AWS_HOME (and may set AWS_CONFIG_FILE), ensures the directory and config file exist with secure permissions, and returns 1 on failure to create a usable directory.
 function _aws_config_home() {
 	for dir in "${GEODESIC_AWS_HOME}" "${LOCAL_HOME}/.aws" "${HOME}/.aws"; do
 		if [ -d "${dir}" ]; then
@@ -80,7 +81,7 @@ function aws_choose_role() {
 }
 
 # Usage: aws_sdk_assume_role <role> [command...]
-# If no command is given, a subshell is started with the role.
+# aws_sdk_assume_role sets ASSUME_ROLE and AWS_PROFILE to the specified role (or an interactively chosen role if none specified) and either launches a login subshell that preserves shell history or executes a given command with that profile, then restores the previous ASSUME_ROLE.
 function aws_sdk_assume_role() {
 	local role=$1
 	shift
@@ -108,7 +109,12 @@ function aws_sdk_assume_role() {
 }
 
 # Asks AWS what the currently active identity is and
-# sets environment variables accordingly
+# export_current_aws_role sets ASSUME_ROLE to reflect the currently active AWS identity.
+# It inspects the current STS caller identity and the active profile (AWS_PROFILE or AWS_VAULT),
+# attempts to map the active ARN to a more descriptive profile name by consulting the AWS config
+# and credentials files (handling normal IAM roles and Identity Center/SSO roles), warns and
+# exports a redacted marker when the environment profile disagrees with the active identity,
+# and unsets ASSUME_ROLE and returns when no identity can be determined.
 function export_current_aws_role() {
 	local role_name role_names
 	# Could be a primary or assumed role. If we have assumed a role, cut off the session name.
@@ -251,7 +257,9 @@ function export_current_aws_role() {
 
 # Keep track of AWS credentials and updates to AWS role environment variables.
 # When changes are noticed, update prompt with current role.
-unset GEODESIC_AWS_ROLE_CACHE # clear out value inherited from supershell
+unset GEODESIC_AWS_ROLE_CACHE # refresh_current_aws_role_if_needed checks whether the active AWS role context has changed and updates cached state if necessary.
+# 
+# It computes a fingerprint from the exported AWS_PROFILE, the modification time of the shared credentials file, and AWS_ACCESS_KEY_ID; if the fingerprint differs from GEODESIC_AWS_ROLE_CACHE it calls export_current_aws_role and updates GEODESIC_AWS_ROLE_CACHE with the new fingerprint.
 function refresh_current_aws_role_if_needed() {
 	local is_exported="^declare -[^ x]*x[^ x]* "
 	local aws_profile=$(declare -p AWS_PROFILE 2>/dev/null)
@@ -268,4 +276,4 @@ function refresh_current_aws_role_if_needed() {
 # so only use refresh_current_aws_role_if_needed if they are disabled or overridden
 if [[ ($AWS_OKTA_ENABLED != "true" && ${AWS_VAULT_ENABLED:-false} != "true") || -n $AWS_PROFILE ]]; then
 	PROMPT_HOOKS+=("refresh_current_aws_role_if_needed")
-fi
+fi

rootfs/etc/profile.d/fzf.sh

@@ -10,7 +10,8 @@ fi
 
 # A lot of terminals (including Apple's) do not support 24-bit color and the mapping from 24-bit to 8-bit is horrible.
 # So most of the color schemes are limited to the 256 ANSI colors that nearly every terminal supports.
-# Color schemes that only render properly with 24_bit color support are suffixed with _24
+# _set_fzf_default_opts builds and exports FZF_DEFAULT_OPTS based on the given color scheme.
+# The first argument selects the color scheme (e.g., solar_24, solarized_dark, solarized_light, mild, dark, light, 16, bw); when omitted or unrecognized, a mild/default palette is used.
 
 function _set_fzf_default_opts() {
 	local gray1="232"
@@ -75,4 +76,4 @@ _set_fzf_default_opts "$FZF_COLORS"
 # Requires fzf v0.18.0 or later
 if [[ $PROMPT_STYLE == plain && ! $FZF_DEFAULT_OPTS =~ --no-unicode ]]; then
 	FZF_DEFAULT_OPTS="${FZF_DEFAULT_OPTS:+${FZF_DEFAULT_OPTS} }--no-unicode"
-fi
+fi

rootfs/etc/profile.d/prompt.sh

@@ -63,6 +63,11 @@ function reload() {
 # Define our own prompt
 PROMPT_HOOKS+=("geodesic_prompt")
 KUBE_PS1_SYMBOL_ENABLE=${KUBE_PS1_SYMBOL_ENABLE:-false}
+# geodesic_prompt Constructs and installs the interactive shell prompt (PS1) using configured style, role, secrets, Terraform and Kubernetes state, and optional banner.
+# 
+# geodesic_prompt selects glyphs and marks based on PROMPT_STYLE (plain, unicode, fancy, or default), computes a level indicator from SHLVL, and sets status/role indicators based on ASSUME_ROLE.
+# It detects active secret environment variables listed in PROMPT_SECRET_ENVS and appends an indicator if any are set, integrates Terraform prompt lines when GEODESIC_TF_PROMPT_ACTIVE is enabled, and adapts the kube prompt prefix for KUBE_PS1.
+# The final PS1 includes an optional BANNER line (with namespace when configured) followed by the directory/host/role segment and prompt glyphs; when no BANNER is defined, PS1 contains only the Terraform and directory segments.
 function geodesic_prompt() {
 
 	case $PROMPT_STYLE in
@@ -211,4 +216,4 @@ function geodesic_prompt_style() {
 		unset PROMPT_STYLE
 		;;
 	esac
-}
+}

rootfs/templates/wrapper-body.sh

@@ -264,10 +264,12 @@ function _running_shell_pids() {
 	debug_and_run --noerr docker exec "${DOCKER_NAME}" list-wrapper-shells
 }
 
+# _our_shell_pid prints the wrapper shell PID inside the container for the current WRAPPER_PID.
 function _our_shell_pid() {
 	debug_and_run --noerr docker exec "${DOCKER_NAME}" list-wrapper-shells "$WRAPPER_PID" || true
 }
 
+# _running_shell_count echoes the number of running shell PIDs detected in the current container.
 function _running_shell_count() {
 	local count
 	mapfile -t count < <(_running_shell_pids || true)
@@ -285,7 +287,7 @@ function _on_container_exit() {
 	[ -n "${ON_CONTAINER_EXIT}" ] && command -v "${ON_CONTAINER_EXIT}" >/dev/null && debug_and_run "${ON_CONTAINER_EXIT}"
 }
 
-# Call this function to wait for the container to exit, after all other shells have exited.
+# wait_for_container_exit waits for the Docker container to exit after other shells have terminated, triggers appropriate exit hooks, and prints guidance or forces termination if the container remains running.
 function wait_for_container_exit() {
 	local i n shells
 	n=15
@@ -320,6 +322,7 @@ function wait_for_container_exit() {
 	fi
 }
 
+# run_exit_hooks coordinates shutdown after the terminal detaches: it waits for other interactive shells (if any), reports status to the user, and invokes container- and shell-exit hooks while waiting for the container to terminate.
 function run_exit_hooks() {
 	# This runs as soon as the terminal is detached. It may take moments for the shell to actually exit.
 	# It can then take at least a second for the init process to quit.
@@ -653,6 +656,7 @@ function use() {
 	true
 }
 
+# _polite_stop sends SIGTERM to the Docker container matching NAME, waits up to 8 seconds for it to exit, and re-sends SIGTERM (exiting with code 138) if the container does not stop.
 _polite_stop() {
 	name="$1"
 	[ -n "$name" ] || return 1
@@ -676,6 +680,7 @@ _polite_stop() {
 	return 138
 }
 
+# stop stops a running geodesic container: if a container name is provided as the first target it requests a graceful shutdown of that container; otherwise it finds containers matching DOCKER_NAME and stops the single match, reports none found, or returns an error when multiple matches exist.
 function stop() {
 	exec 1>&2
 	name=${targets[1]}
@@ -711,4 +716,4 @@ elif [ -z "${targets[0]}" ] || [ "${targets[0]}" = "use" ]; then
 	use "${targets[@]}"
 else
 	help
-fi
+fi