docs: Improve function descriptions

Author: hyperupcall

bake

@@ -91,6 +91,29 @@ bake.assert_cmd() {
 	fi
 }
 
+# @description Determine if a flag was passed as an argument
+# @arg $1 string Flag name to test for
+# @arg $@ string Rest of the arguments to search through
+bake.has_flag() {
+	local flag_name="$1"
+
+	if [ -z "$flag_name" ]; then
+		bake.die "Argument must not be empty"
+	fi
+	if ! shift; then
+		bake.die 'Failed to shift'
+	fi
+
+	local arg=
+	for arg; do
+		if [ "$arg" = "$flag_name" ]; then
+			return 0
+		fi
+	done; unset -v arg
+
+	return 1
+}
+
 # @description Change the behavior of Bake. See [guide.md](./docs/guide.md) for details
 # @arg $1 string Name of config property to change
 # @arg $2 string New value of config property
@@ -101,21 +124,26 @@ bake.cfg() {
 	case $cfg in
 	stacktrace)
 		case $value in
-			yes|no) __bake_cfg_stacktrace=$value ;;
-			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'yes' or 'no'" ;;
+			yes) __bake_internal_warn "Passing either 'yes' or 'no' as a value for 'bake.cfg stacktrace' is deprecated. Instead, use either 'on' or 'off'"; __bake_cfg_stacktrace='on' ;;
+			no) __bake_internal_warn "Passing either 'yes' or 'no' as a value for 'bake.cfg stacktrace' is deprecated. Instead, use either 'on' or 'off'"; __bake_cfg_stacktrace='off' ;;
+			on|off) __bake_cfg_stacktrace=$value ;;
+			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'on' or 'off'" ;;
 		esac
 		;;
 	pedantic-task-cd)
 		case $value in
-			yes) trap '__bake_trap_debug' 'DEBUG' ;;
-			no) trap - 'DEBUG' ;;
-			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'yes' or 'no'" ;;
+			yes) __bake_internal_warn "Passing either 'yes' or 'no' as a value for 'bake.cfg pedantic-task-cd' is deprecated. Instead, use either 'on' or 'off'"; trap '__bake_trap_debug' 'DEBUG' ;;
+			no) __bake_internal_warn "Passing either 'yes' or 'no' as a value for 'bake.cfg pedantic-task-cd' is deprecated. Instead, use either 'on' or 'off'"; trap - 'DEBUG' ;;
+			on) trap '__bake_trap_debug' 'DEBUG' ;;
+			off) trap - 'DEBUG' ;;
+			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'on' or 'off'" ;;
 		esac
 		;;
 	big-print)
 		case $value in
-			yes|no) ;;
-			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'yes' or 'no'" ;;
+			yes|no) __bake_internal_warn "Passing either 'yes' or 'no' as a value for 'bake.cfg big-print' is deprecated. Instead, use either 'on' or 'off'" ;;
+			on|off) ;;
+			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'on' or 'off'" ;;
 		esac
 		;;
 	*)
@@ -127,7 +155,7 @@ bake.cfg() {
 # @description Prints stacktrace
 # @internal
 __bake_print_stacktrace() {
-	if [ "$__bake_cfg_stacktrace" = 'yes' ]; then
+	if [ "$__bake_cfg_stacktrace" = 'on' ]; then
 		if __bake_is_color; then
 			printf '\033[4m%s\033[0m\n' 'Stacktrace:'
 		else
@@ -173,11 +201,17 @@ __bake_trap_debug() {
 # @exitcode 1 if should not print color
 # @internal
 __bake_is_color() {
-	if [[ -v NO_COLOR || $TERM == dumb ]]; then
+	local fd="1"
+
+	if [[ ${NO_COLOR+x} || "$TERM" = 'dumb' ]]; then
 		return 1
-	else
+	fi
+
+	if [ -t "$fd" ]; then
 		return 0
 	fi
+
+	return 1
 }
 
 # @description Calls `__bake_internal_error` and terminates with code 1
@@ -240,11 +274,22 @@ __bake_print_tasks() {
 	local str=
 
 	# shellcheck disable=SC1007,SC2034
-	local regex="^(([[:space:]]*function[[:space:]]*)?task\.(.*?)\(\)).*"
+	local regex="^([[:space:]]*function[[:space:]]*)?task\.(.*?)\(\)[[:space:]]*\{[[:space:]]*(#[[:space:]]*(.*))?"
 	local line=
 	while IFS= read -r line || [ -n "$line" ]; do
 		if [[ "$line" =~ $regex ]]; then
-			str+="  -> ${BASH_REMATCH[3]}"$'\n'
+			str+="  -> ${BASH_REMATCH[2]}"
+
+			local task_comment=${BASH_REMATCH[4]}
+			if [ -n "$task_comment" ]; then
+				if __bake_is_color; then
+					str+=$' \033[3m'"($task_comment)"$'\033[0m'
+				else
+					str+=" ($task_comment)"
+				fi
+			fi
+
+			str+=$'\n'
 		fi
 	done < "$BAKE_FILE"; unset -v line
 
@@ -265,7 +310,7 @@ __bake_print_tasks() {
 __bake_print_big() {
 	local print_text="$1"
 
-	if [ "$__bake_cfg_big_print" = 'no' ]; then
+	if [ "$__bake_cfg_big_print" = 'off' ]; then
 		return
 	fi
 
@@ -302,7 +347,6 @@ __bake_parse_args() {
 	unset REPLY; REPLY=
 	local -i total_shifts=0
 
-	# FIXME: bug for when passing -v to child task argument
 	local __bake_arg=
 	for arg; do case $arg in
 	-f)
@@ -323,14 +367,19 @@ __bake_parse_args() {
 		fi
 		;;
 	-v)
-		local bake_version='1.8.2'
+		local bake_version='1.9.0'
 		printf '%s\n' "Version: $bake_version"
+		exit 0
 		;;
 	-h)
 		local flag_help='yes'
 		if ! shift; then
 			__bake_internal_die 'Failed to shift'
 		fi
+		;;
+	*)
+		break
+		;;
 	esac done
 
 	if [ -n "$BAKE_FILE" ]; then
@@ -373,8 +422,8 @@ __bake_parse_args() {
 # @description Main function
 # @internal
 __bake_main() {
-	__bake_cfg_stacktrace='no'
-	__bake_cfg_big_print='yes'
+	__bake_cfg_stacktrace='off'
+	__bake_cfg_big_print='on'
 
 	# Environment boilerplate
 	set -ETeo pipefail
@@ -384,7 +433,7 @@ __bake_main() {
 		LC_TELEPHONE='C' LC_MEASUREMENT='C' LC_IDENTIFICATION='C' LC_ALL='C'
 	trap '__bake_trap_err' 'ERR'
 	trap ':' 'INT' # Ensure Ctrl-C ends up printing <- ERROR ==== etc.
-	bake.cfg pedantic-task-cd 'no'
+	bake.cfg pedantic-task-cd 'off'
 
 	# Parse arguments
 	# Set `BAKE_{ROOT,FILE}`
@@ -437,8 +486,8 @@ __bake_main() {
 		local shouldTestNextLine='no'
 		while IFS= read -r line; do
 			if [ "$shouldTestNextLine" = 'yes' ]; then
-				if [[ $line == *'bake.cfg'*big-print*no* ]]; then
-					__bake_cfg_big_print='no'
+				if [[ $line == *'bake.cfg'*big-print*@(no|off)* ]]; then
+					__bake_cfg_big_print='off'
 				fi
 				shouldTestNextLine='no'
 			fi

pkg/src/util/util.sh

@@ -1,5 +1,6 @@
 # shellcheck shell=bash
 
+# @description Initialize global variables required for shopt and trap functions
 # @internal
 core.private.util.init() {
 	if [ ${___global_bash_core_has_init__+x} ]; then
@@ -11,6 +12,7 @@ core.private.util.init() {
 	declare -ga ___global_shopt_stack___=()
 }
 
+# @description Function that runs handlers for a particular signal
 # @internal
 core.private.util.trap_handler_common() {
 	local signal_spec="$1"
@@ -35,6 +37,7 @@ core.private.util.trap_handler_common() {
 	done; unset -v trap_handler
 }
 
+# @internal
 core.private.util.validate_args() {
 	local function="$1"
 	local arg_count="$2"
@@ -48,6 +51,7 @@ core.private.util.validate_args() {
 	fi
 }
 
+# @internal
 core.private.util.validate_signal() {
 	local function="$1"
 	local signal_spec="$2"
@@ -66,7 +70,7 @@ core.private.util.validate_signal() {
 	fi
 }
 
-# @description Prints the current error stored
+# @description Prints the current errors
 # @internal
 core.private.util.err_print() {
 	printf '%s\n' 'Error found:'