all: improve function docs

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

distrobox

@@ -24,9 +24,13 @@ set -o nounset
 
 version="1.7.1.0"
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
+# Expected global variables:
+#   version: distrobox version
+# Expected env variables:
+#   None
 # Outputs:
 #   print usage with examples.
 show_help() {

distrobox-assemble

@@ -231,16 +231,18 @@ if [ ! -e "${input_file}" ]; then
 	exit 1
 fi
 
-# Create distrobox with parameters parsed from ini file.
+# run_distrobox will create distrobox with parameters parsed from ini file.
 # Arguments:
-#   name    = 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
+#   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
+# Expected env variables:
+#   None
 # Outputs:
 #   execution of the proper distrobox-create command.
 run_distrobox() {
@@ -445,9 +447,13 @@ run_distrobox() {
 	fi
 }
 
-# Sanitize an input, add single/double quotes and escapes
+# sanitize_variable will sanitize an input, add single/double quotes and escapes
 # Arguments:
-#   a value string
+#   variable: string
+# Expected global variables:
+#   None
+# Expected env variables:
+#   None
 # Outputs:
 #   a value string sanitized
 sanitize_variable() {
@@ -464,11 +470,13 @@ sanitize_variable() {
 	echo "${variable}"
 }
 
-# Parse input file and call distrobox-create accordingly
+# parse_file will read and parse input file and call distrobox-create accordingly
 # Arguments:
-#   path of the manifest file to parse
+#   file: stirng path of the manifest file to parse
 # Expected global variables:
-#   tmpfile = string name of the tmpfile to read
+#   tmpfile: string name of the tmpfile to read
+# Expected env variables:
+#   None
 # Outputs:
 #   None
 parse_file() {

distrobox-create

@@ -153,9 +153,15 @@ fi
 [ "${verbose}" = "true" ] && verbose=1
 [ "${verbose}" = "false" ] && verbose=0
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
+# Expected global variables:
+#   version: string distrobox version
+#   container_image_default: string default container image to use
+#   container_name_default:  string default container name to use
+# Expected env variables:
+#   None
 # Outputs:
 #   print usage with examples.
 show_help() {
@@ -225,12 +231,14 @@ Compatibility:
 EOF
 }
 
-# Print list of compatible images to stdou, caching locally in a file.
+# show_compatibility will print the list of compatible images to stdout, caching locally in a file.
 # Arguments:
 #   None
 # Expected global variables:
-#   app_cache_dir = cache dir to write to
-#   version       = distrobox version
+#   app_cache_dir: cache dir to write to
+#   version:       distrobox version
+# Expected env variables:
+#   None
 # Outputs:
 #   print usage with examples.
 show_compatibility() {
@@ -554,12 +562,15 @@ if [ -z "${distrobox_entrypoint_path}" ] || [ -z "${distrobox_export_path}" ]; t
 	exit 127
 fi
 
-# Clone a container as a snapshot.
+# get_clone_image will return the image name of a cloned existing container taken
+# as input.
 # Arguments:
 #   None
 # Expected global variables:
-#   container_manager = string container manager to use
-#   container_clone   = string container name to clone
+#   container_manager: string container manager to use
+#   container_clone: string container name to clone
+# Expected env variables:
+#   None
 # Outputs:
 #   prints the image name of the newly cloned container
 get_clone_image() {
@@ -598,32 +609,34 @@ get_clone_image() {
 	return 0
 }
 
-# Generate Podman or Docker command to execute.
+# generate_create_command will produce a 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
+#   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
+# Expected env variables:
+#   None
 # Outputs:
 #   prints the podman, docker or lilipod command to create the distrobox container
 generate_create_command() {

distrobox-enter

@@ -41,15 +41,16 @@ app_cache_dir=${XDG_CACHE_HOME:-"${HOME}/.cache"}/distrobox
 
 trap cleanup TERM INT HUP EXIT
 
-# Generate Podman, Docker or Lilipod command to execute.
+# cleanup will remove fifo and temp files, and print to stdout
+# container's logs in case of error and verbose.
 # 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
+#   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:
@@ -151,13 +152,13 @@ fi
 [ "${verbose}" = "true" ] && verbose=1
 [ "${verbose}" = "false" ] && verbose=0
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
 # Expected global variables:
-#   version = string distrobox version
+#   version: distrobox version
 # Expected env variables:
-#   USER
+#   None
 # Outputs:
 #   print usage with examples.
 show_help() {
@@ -341,19 +342,19 @@ if [ "${rootful}" -ne 0 ]; then
 	container_manager="${distrobox_sudo_program-} ${container_manager}"
 fi
 
-# Generate Podman, Docker or Lilipod command to execute.
+# generate_enter_command will produce a Podman, Docker or Lilipod command to execute to enter the container.
 # 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
+#   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:

distrobox-ephemeral

@@ -86,9 +86,13 @@ done
 [ "${verbose}" = "true" ] && verbose=1
 [ "${verbose}" = "false" ] && verbose=0
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
+# Expected global variables:
+#   version: distrobox version
+# Expected env variables:
+#   None
 # Outputs:
 #   print usage with examples.
 show_help() {
@@ -202,14 +206,16 @@ if [ "${rootful}" -ne 0 ]; then
 	extra_flags="${extra_flags} --root"
 fi
 
-# Generate distrobox-create command to execute.
+# generate_ephemeral_create_command will produce a 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
+# Expected env variables:
+#   None
 # Outputs:
 #   prints the distrobox-create command handling special flags
 generate_ephemeral_create_command() {
@@ -237,6 +243,17 @@ generate_ephemeral_create_command() {
 	printf "%s" "${result_command}"
 }
 
+# cleanup will ensure we remove the ephemeral container
+# Arguments:
+#   None
+# Expected global variables:
+#   name: string the name of the container
+#   extra_flags: string extra flags to append to the distrobox command
+#   distrobox_path: string path to the distrobox script
+# Expected env variables:
+#   None
+# Outputs:
+#   None
 cleanup() {
 	trap - TERM INT HUP
 	# shellcheck disable=SC2086