all: improve functions' documentation

Signed-off-by: Luca Di Maio <[email protected]>

distrobox-assemble

@@ -71,9 +71,13 @@ if [ -n "${SUDO_USER}" ] || [ -n "${DOAS_USER}" ]; then
 	exit 1
 fi
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
+# Expected global variables:
+#   version: string distrobox version
+# Expected env variables:
+#   None
 # Outputs:
 #   print usage with examples.
 show_help() {
@@ -196,7 +200,14 @@ fi
 
 # Create distrobox with parameters parsed from ini file.
 # Arguments:
-#   name of the distrobox.
+#   name    = name of the distrobox.
+# Expected global variables:
+#   boxname = string name of the target container
+#   tmpfile = string name of the tmpfile to read
+#   delete  = bool delete container
+#   replace = bool replace container
+#   dryrun  = bool dryrun (only print, no execute)
+# verbose   = bool verbose
 # Outputs:
 #   execution of the proper distrobox-create command.
 run_distrobox() {
@@ -220,7 +231,7 @@ run_distrobox() {
 
 	# We're going to delete, not create!
 	if [ "${delete}" -ne 0 ] || [ "${replace}" -ne 0 ]; then
-		printf " - Deleting %s... \n" "${name}"
+		printf " - Deleting %s...\n" "${name}"
 
 		if [ "${dryrun}" -eq 0 ]; then
 			# shellcheck disable=SC2086,2248
@@ -233,7 +244,7 @@ run_distrobox() {
 	fi
 
 	# We're going to create!
-	printf " - Creating %s... \n" "${name}"
+	printf " - Creating %s...\n" "${name}"
 
 	# If distrobox already exist, and we have replace enabled, destroy the container
 	# we have to recreate it.
@@ -420,6 +431,8 @@ sanitize_variable() {
 # Parse input file and call distrobox-create accordingly
 # Arguments:
 #   path of the manifest file to parse
+# Expected global variables:
+#   tmpfile = string name of the tmpfile to read
 # Outputs:
 #   None
 parse_file() {

distrobox-create

@@ -228,6 +228,9 @@ EOF
 # Print list of compatible images to stdou, caching locally in a file.
 # Arguments:
 #   None
+# Expected global variables:
+#   app_cache_dir = cache dir to write to
+#   version       = distrobox version
 # Outputs:
 #   print usage with examples.
 show_compatibility() {
@@ -540,12 +543,22 @@ if [ -n "${container_additional_volumes}" ]; then
 	done
 fi
 
+# Check that we have a complete distrobox installation or
+# entrypoint and export will not work.
+if [ -z "${distrobox_entrypoint_path}" ] || [ -z "${distrobox_export_path}" ]; then
+	printf >&2 "Error: no distrobox-init found in %s\n" "${PATH}"
+	exit 127
+fi
+
 # Clone a container as a snapshot.
 # Arguments:
 #   None
+# Expected global variables:
+#   container_manager = string container manager to use
+#   container_clone   = string container name to clone
 # Outputs:
 #   prints the image name of the newly cloned container
-clone_container() {
+get_clone_image() {
 	# We need to clone a container.
 	# to do this we will commit the container and create a new tag. Then use it
 	# as image for the new container.
@@ -584,9 +597,32 @@ clone_container() {
 # Generate Podman or Docker command to execute.
 # Arguments:
 #   None
+# Expected global variables:
+#   container_manager  = string container manager to use
+#   container_name     = string container name
+#   container_image    = string container image
+#   container_manager_additional_flags = string container manager additional flags to use
+#   container_hostname = string container hostname
+#   container_additional_packages = string additional packages
+#   container_pre_init_hook = string pre init hooks
+#   container_init_hook = string init hooks
+#   container_user_home = string user's home path
+#   container_user_name = string user's username
+#   container_user_uid  = string user's UID
+#   container_user_gid  = string user's GID
+#   container_home_prefix = string container's custom home prefix
+#   container_user_custom_home = string container's custom home path
+#   init    = bool initful
+#   nvidia  = bool nvidia integration
+#   rootful = bool rootful
+#   unshare_devsys  = bool unshare devsys
+#   unshare_groups  = bool unshare groups
+#   unshare_ipc     = bool unshare ipc
+#   unshare_netns   = bool unshare netns
+#   unshare_process = bool unshare proc
 # Outputs:
 #   prints the podman, docker or lilipod command to create the distrobox container
-generate_command() {
+generate_create_command() {
 	# Set the container hostname the same as the container name.
 	result_command="${container_manager} create"
 	# use the host's namespace for ipc, network, pid, ulimit
@@ -854,19 +890,12 @@ generate_command() {
 	printf "%s" "${result_command}"
 }
 
-# Check that we have a complete distrobox installation or
-# entrypoint and export will not work.
-if [ -z "${distrobox_entrypoint_path}" ] || [ -z "${distrobox_export_path}" ]; then
-	printf >&2 "Error: no distrobox-init found in %s\n" "${PATH}"
-	exit 127
-fi
-
 # dry run mode, just generate the command and print it. No creation.
 if [ "${dryrun}" -ne 0 ]; then
 	if [ -n "${container_clone}" ]; then
 		container_image="${container_clone}"
 	fi
-	cmd="$(generate_command)"
+	cmd="$(generate_create_command)"
 	cmd="$(echo "${cmd}" | sed 's/\t//g')"
 	printf "%s\n" "${cmd}"
 	exit 0
@@ -890,8 +919,9 @@ fi
 # if we are using the clone flag, let's set the image variable
 # to the output of container duplication
 if [ -n "${container_clone}" ]; then
-	container_image="$(clone_container)"
+	container_image="$(get_clone_image)"
 fi
+
 # First, check if the image exists in the host or auto-pull is enabled
 # If not prompt to download it.
 if [ "${container_always_pull}" -eq 1 ] ||
@@ -929,7 +959,7 @@ fi
 
 # Generate the create command and run it
 printf >&2 "Creating '%s' using image %s\t" "${container_name}" "${container_image}"
-cmd="$(generate_command)"
+cmd="$(generate_create_command)"
 # Eval the generated command. If successful display an helpful message.
 # shellcheck disable=SC2086
 if eval ${cmd} > /dev/null; then

distrobox-enter

@@ -23,16 +23,36 @@
 #	HOME
 #	USER
 # Optional env variables:
+#	DBX_CONTAINER_ALWAYS_PULL
+#	DBX_CONTAINER_CUSTOM_HOME
+#	DBX_CONTAINER_GENERATE_ENTRY
+#	DBX_CONTAINER_HOME_PREFIX
+#	DBX_CONTAINER_HOSTNAME
+#	DBX_CONTAINER_IMAGE
 #	DBX_CONTAINER_MANAGER
 #	DBX_CONTAINER_NAME
 #	DBX_CONTAINER_CLEAN_PATH
+#	DBX_NON_INTERACTIVE
 #	DBX_SKIP_WORKDIR
 #	DBX_SUDO_PROGRAM
 
 app_cache_dir=${XDG_CACHE_HOME:-"${HOME}/.cache"}/distrobox
 
 trap cleanup TERM INT HUP EXIT
 
+# Generate Podman, Docker or Lilipod command to execute.
+# Arguments:
+#   None
+# Expected global variables:
+#   container_manager = string container manager to use
+#   container_name    = string container name
+#   app_cache_dir     = string cache dire to write file into
+#   logs_pid     = string pid of the podman/docker logs process
+#   verbose      = bool verbose
+# Expected env variables:
+#   None
+# Outputs:
+#   None
 cleanup() {
 	rm -f "${app_cache_dir}/.${container_name}.fifo"
 	if [ -n "${logs_pid:-}" ]; then
@@ -132,6 +152,10 @@ fi
 # Print usage to stdout.
 # Arguments:
 #   None
+# Expected global variables:
+#   version = string distrobox version
+# Expected env variables:
+#   USER
 # Outputs:
 #   print usage with examples.
 show_help() {
@@ -318,19 +342,37 @@ fi
 # Generate Podman, Docker or Lilipod command to execute.
 # Arguments:
 #   None
+# Expected global variables:
+#   container_manager = string container manager to use
+#   container_name    = string container name
+#   container_manager_additional_flags = string container manager additional flags to use
+#   container_command = string container command to execute
+#   container_home    = string container's home path
+#   container_path    = string container's default PATH variable
+#   headless     = bool headless mode
+#   skip_workdir = bool skip workdir
+#   verbose      = bool verbose
+#   unshare_groups
+#   distrobox_enter_path
+# Expected env variables:
+#   PATH
+#   USER
+#   PWD
+#   XDG_DATA_DIRS
+#   XDG_CONFIG_DIRS
 # Outputs:
 #   prints the podman, docker or lilipod command to enter the distrobox container
-generate_command() {
+generate_enter_command() {
 	result_command="${container_manager} exec"
 	result_command="${result_command}
 		--interactive"
 	result_command="${result_command}
 		--detach-keys=\"\""
 
+	# In case of initful systems or unshared groups, we don't enter directly
+	# as our user, but we instead enter as root, and then su $USER, in order
+	# to trigger a proper login
 	if [ "${unshare_groups:-0}" -eq 1 ]; then
-		# In case of initful systems or unshared groups, we don't enter directly
-		# as our user, but we instead enter as root, and then su $USER, in order
-		# to trigger a proper login
 		result_command="${result_command}
 			--user='root'"
 
@@ -342,6 +384,7 @@ generate_command() {
 		fi
 		container_command_login="${container_command_login} -c \"\\\$(getent passwd ${USER} | cut -f 7 -d :) -l\""
 		if [ -n "${container_command}" ]; then
+			# escape $ in order to avoid evaluation by the login shell
 			container_command="$(echo "${container_command}" | sed 's/\$/\\\$/g')"
 			container_command="${container_command_login} -c \"${container_command}\""
 		fi
@@ -384,6 +427,7 @@ generate_command() {
 		--env \"CONTAINER_ID=${container_name}\""
 	result_command="${result_command}
 		--env \"DISTROBOX_ENTER_PATH=${distrobox_enter_path}\""
+
 	# Loop through all the environment vars
 	# and export them to the container.
 	set +o xtrace
@@ -437,7 +481,7 @@ generate_command() {
 
 	# Ensure the standard FHS program paths are in XDG_DATA_DIRS environment
 	standard_paths="/usr/local/share /usr/share"
-	container_paths="${XDG_DATA_DIRS:=}"
+	container_paths="${XDG_DATA_DIRS:-}"
 	# add to the XDG_DATA_DIRS only after the host's paths, and only if not already present.
 	for standard_path in ${standard_paths}; do
 		pattern="(:|^)${standard_path}(:|$)"
@@ -461,7 +505,7 @@ generate_command() {
 
 	# Ensure the standard FHS program paths are in XDG_CONFIG_DIRS environment
 	standard_paths="/etc/xdg"
-	container_paths="${XDG_CONFIG_DIRS:=}"
+	container_paths="${XDG_CONFIG_DIRS:-}"
 	# add to the XDG_CONFIG_DIRS only after the host's paths, and only if not already present.
 	for standard_path in ${standard_paths}; do
 		pattern="(:|^)${standard_path}(:|$)"
@@ -516,8 +560,7 @@ eval "$(${container_manager} inspect --type container --format \
 
 # dry run mode, just generate the command and print it. No execution.
 if [ "${dryrun}" -ne 0 ]; then
-	cmd="$(generate_command)"
-	cmd="$(echo "${cmd}" | sed 's/\t//g')"
+	cmd="$(generate_enter_command | sed 's/\t//g')"
 	printf "%s\n" "${cmd}"
 	exit 0
 fi
@@ -567,11 +610,12 @@ fi
 # If the container is not already running, we need to start if first
 if [ "${container_status}" != "running" ]; then
 	# If container is not running, start it first
+	#
 	# Here, we save the timestamp before launching the start command, so we can
 	# be sure we're working with this very same session of logs later.
-	#
 	log_timestamp="$(date +%FT%T.%N%:z)"
 	${container_manager} start "${container_name}" > /dev/null
+	#
 	# Check if the container is going in error status earlier than the
 	# entrypoint
 	if [ "$(${container_manager} inspect \
@@ -633,6 +677,6 @@ if [ "${container_status}" != "running" ]; then
 fi
 
 # Generate the exec command and run it
-cmd="$(generate_command)"
+cmd="$(generate_enter_command)"
 # shellcheck disable=SC2086
 eval ${cmd}

distrobox-ephemeral

@@ -173,9 +173,14 @@ fi
 # Generate distrobox-create command to execute.
 # Arguments:
 #   None
+# Expected global variables:
+#   distrobox_path = string distrobox path
+#   name         = string container name
+#   extra_flags  = string extra flags to inject
+#   create_flags = string create extra flags to inject
 # Outputs:
 #   prints the distrobox-create command handling special flags
-generate_command() {
+generate_ephemeral_create_command() {
 	result_command="${distrobox_path}/distrobox-create"
 	if [ -n "${container_manager_additional_flags}" ]; then
 		result_command="${result_command} \
@@ -206,7 +211,7 @@ cleanup() {
 	"${distrobox_path}"/distrobox-rm ${extra_flags} --force "${name}" --yes
 }
 
-cmd="$(generate_command)"
+cmd="$(generate_ephemeral_create_command)"
 # shellcheck disable=SC2086
 eval ${cmd}
 # shellcheck disable=SC2086