all: improve function docs

Signed-off-by: Luca Di Maio <luca.dimaio1@gmail.com>

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,7 +206,7 @@ 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:
@@ -210,6 +214,8 @@ fi
 #   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

distrobox-export

@@ -67,7 +67,7 @@ done
 # Arguments:
 #   None
 # Expected global variables:
-#   version: string distrobox version
+#   version: distrobox version
 # Expected env variables:
 #   None
 # Outputs:
@@ -311,20 +311,23 @@ else
 	exported_app_label=" ${exported_app_label}"
 fi
 
-# Print generated script from template
+# generate_script will generate a script from template. This script will wrap the
+# exported binary in order to ensure it will be executed in the right container.
 # Arguments:
-#	none it will use the ones set up globally
+#	None
+# Expected global variables:
+#   CONTAINER_ID: id of the current container
+#   container_command_suffix: string to postpone to the command to launch
+#   container_name:  string name of this container
+#   dest_path: string path where to export the binary
+#   enter_flags:  string extra flags to append to the distrobox enter command
+#   exported_bin: string path to the binary to export
+#   exported_delete: bool delete the binary exported
+#   extra_flags:  string extra flags to append to the exported app command
+#   rootful: bool if this is a rootful container
+#   sudo_prefix: string sudo command to prepend to the exported command
 # Expected env variables:
-#   CONTAINER_ID = id of the current container
-#   container_command_suffix = string to postpone to the command to launch
-#   container_name =  string name of this container
-#   dest_path       = string path where to export the binary
-#   enter_flags =  string extra flags to append to the distrobox enter command
-#   exported_bin    = string path to the binary to export
-#   exported_delete = bool delete the binary exported
-#   extra_flags =  string extra flags to append to the exported app command
-#   rootful     = bool if this is a rootful container
-#   sudo_prefix = string sudo command to prepend to the exported command
+#   None
 # Outputs:
 #	print generated script.
 generate_script() {
@@ -343,18 +346,20 @@ EOF
 	return $?
 }
 
-# Export binary to destination directory.
+# export_binary will export selected binary to destination directory.
 # the following function will use generate_script to create a shell script in
 # dest_path that will execute the exported binary in the selected distrobox.
 #
 # Arguments:
-#	none it will use the ones set up globally
+#	None
+# Expected global variables:
+#   CONTAINER_ID: id of the current container
+#   container_name: string name of this container
+#   dest_path: string path where to export the binary
+#   exported_bin: string path to the binary to export
+#   exported_delete: bool delete the binary exported
 # Expected env variables:
-#   CONTAINER_ID = id of the current container
-#   container_name =  string name of this container
-#   dest_path       = string path where to export the binary
-#   exported_bin    = string path to the binary to export
-#   exported_delete = bool delete the binary exported
+#   None
 # Outputs:
 #	a generated_script in dest_path
 #	or error code.
@@ -403,23 +408,25 @@ export_binary() {
 	return 3
 }
 
-# Export graphical application to the host.
+# export_application will export input graphical application to the host.
 # the following function will scan the distrobox for desktop and icon files for
 # the selected application. It will then put the needed icons in the host's icons
 # directory and create a new .desktop file that will execute the selected application
 # in the distrobox.
 #
 # Arguments:
-#	none it will use the ones set up globally
+#	None
+# Expected global variables:
+#   CONTAINER_ID: id of the current container
+#   container_command_prefix: string to prepend to the command to launch
+#   container_name:  string name of this container
+#   exported_app:   string name of the app to export
+#   exported_app_label: string label to use to mark the exported app
+#   exported_delete:  bool if we want to delete or not
+#   extra_flags:  string extra flags to append to the exported app command
+#   host_home: home path ofr the host, where to search desktop files
 # Expected env variables:
-#   CONTAINER_ID = id of the current container
-#   container_command_prefix = string to prepend to the command to launch
-#   container_name =  string name of this container
-#   exported_app  =   string name of the app to export
-#   exported_app_label = string label to use to mark the exported app
-#   exported_delete    =  bool if we want to delete or not
-#   extra_flags =  string extra flags to append to the exported app command
-#   host_home   = home path ofr the host, where to search desktop files
+#   None
 # Outputs:
 #	needed icons in /run/host/$host_home/.local/share/icons
 #	needed desktop files in /run/host/$host_home/.local/share/applications
@@ -602,14 +609,16 @@ export_application() {
 	fi
 }
 
-# List exported applications in canonical directories.
+# list_exported_applications will print all exported applications in canonical directories.
 # the following function will list exported desktop files from this container.
 #
 # Arguments:
-#	none
+#	None
+# Expected global variables:
+#   host_home: home path ofr the host, where to search desktop files
+#   CONTAINER_ID: id of the current container
 # Expected env variables:
-#   host_home    = home path ofr the host, where to search desktop files
-#   CONTAINER_ID = id of the current container
+#   None
 # Outputs:
 #	a list of exported apps
 #	or error code.
@@ -636,15 +645,17 @@ list_exported_applications() {
 	done
 }
 
-# List exported binaries.
+# list_exported_binaries will print all exported binaries.
 # the following function will list exported desktop files from this container.
 # If no export-path is specified, it searches in the default path.
 #
 # Arguments:
-#	none
+#	None
+# Expected global variables:
+#   dest_path: destination path where to search binaries
+#   CONTAINER_ID: id of the current container
 # Expected env variables:
-#   dest_path    = destination path where to search binaries
-#   CONTAINER_ID = id of the current container
+#	None
 # Outputs:
 #	a list of exported apps
 #	or error code.

distrobox-generate-entry

@@ -81,9 +81,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() {

distrobox-host-exec

@@ -33,9 +33,13 @@ sudo_command=""
 verbose=0
 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-init

@@ -50,9 +50,14 @@ rootful=0
 upgrade=0
 verbose=0
 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() {
@@ -207,9 +212,13 @@ if stat /run/host/etc/shadow > /dev/null &&
 	rootful=1
 fi
 
-# Print mount flags considered "locked".
+# get_locked_mount_flags will print mount flags considered "locked".
 # Arguments:
-# 	src (path to the file/directory)
+# 	src: path to the file/directory
+# Expected env variables:
+#	None
+# Expected global variables:
+#	None
 # Outputs:
 # 	Comma-separated list of locked mount flags
 get_locked_mount_flags() {
@@ -252,6 +261,10 @@ get_locked_mount_flags() {
 # busybox systems, and we need the path even for broken links.
 # Arguments:
 #	source file
+# Expected env variables:
+#	None
+# Expected global variables:
+#	None
 # Outputs:
 #	original path the link is pointing
 init_readlink() {
@@ -259,11 +272,15 @@ init_readlink() {
 	ls -l "${1}" | grep -Eo '\->.*' | cut -d' ' -f2- | sed 's|\.\./|/|g'
 }
 
-# Bind mount or error.
+# mount_bind will perform a bind mount for inputs or error
 # Arguments:
-#   source_dir
-#	target_dir
-#	mount_flags -> optional
+#   source_dir: string what to mount
+#	target_dir: string where to mount
+#	mount_flags: list of mount flags -> optional
+# Expected env variables:
+#	None
+# Expected global variables:
+#	None
 # Outputs:
 #   No output if all ok
 #	Error if not

distrobox-list

@@ -88,9 +88,13 @@ if [ "$(id -ru)" -ne 0 ]; then
 fi
 [ -n "${DBX_CONTAINER_MANAGER}" ] && container_manager="${DBX_CONTAINER_MANAGER}"
 
-# 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-rm

@@ -107,9 +107,13 @@ fi
 container_name_default="my-distrobox"
 container_name_list=""
 
-# 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() {
@@ -278,13 +282,15 @@ if [ -z "${container_name_list}" ]; then
 	container_name_list="${container_name_default}"
 fi
 
-# Delete exported apps and bins for container to delete.
+# cleanup_exports will remove exported apps and bins for container to delete.
 # Arguments:
-#   container_name = string container name
+#   container_name: string container name
 # Expected global variables:
-#   distrobox_flags = string additional distrobox flags to use
+#   distrobox_flags: string additional distrobox flags to use
+# Expected env variables:
+#   None
 # Outputs:
-#   none.
+#   None
 cleanup_exports() {
 	container_name="$1"
 	IFS='¤'
@@ -314,18 +320,20 @@ cleanup_exports() {
 	done
 }
 
-# Delete containers.
+# delete_container will remove input container
 # Arguments:
-#   container_name    = string container name
+#   container_name: string container name
 # Expected global variables:
-#   container_manager = string container manager to use
-#   distrobox_flags   = string distrobox additional flags
-#   non_interactive   = bool non interactive mode
-#   force_flag = bool force mode
-#   rm_home    = bool remove home
-#   verbose    = bool verbose
+#   container_manager: string container manager to use
+#   distrobox_flags: string distrobox additional flags
+#   non_interactive: bool non interactive mode
+#   force_flag: bool force mode
+#   rm_home: bool remove home
+#   verbose: bool verbose
+# Expected env variables:
+#   None
 # Outputs:
-#   none.
+#   None
 delete_container() {
 	container_name="$1"
 	# Inspect the container we're working with.

distrobox-stop

@@ -102,9 +102,13 @@ fi
 
 [ -n "${DBX_SUDO_PROGRAM}" ] && distrobox_sudo_program="${DBX_SUDO_PROGRAM}"
 
-# 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-upgrade

@@ -85,9 +85,13 @@ fi
 # Declare it AFTER config sourcing because we do not want a default name set.
 container_name=""
 
-# 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() {

install

@@ -23,7 +23,7 @@ next=0
 verbose=0
 version=1.7.1.0
 
-# Print usage to stdout.
+# show_help will print usage to stdout.
 # Arguments:
 #   None
 # Outputs: