docs: Update functions

Author: hyperupcall

README.md

@@ -4,40 +4,47 @@ Core functions for any Bash program
 
 ## Summary
 
-The following are functions available for use. See [api.md](./docs/api.md) for more details
-
-### `init`
-
-- `core.util.init`
-
-Initialize global variables used by other functions
-
-Add and remove traps. With these, multiple packages can add or remove traps handlers for signals
+The following is a brief overview of the available functions. See [api.md](./docs/api.md) for more details
 
 ### `trap`
 
+Add or remove multiple functions at a time to any set of signals. Without these, it is impossible to trap a signal without erasing a previous one
+
 - `core.trap_add`
 - `core.trap_remove`
 
 ### `shopt`
 
+Enable or disable a shell option. Enabling a shell option adds it to a hidden stack. When that shell option is no longer needed, it should be removed by popping it from the stack
+
 - `core.shopt_push`
 - `core.shopt_pop`
 
 ### `err`
 
-I suppose it can look redundant (compared to `if ! fn; then :; fi`), but it can help make errors a bit more safe in larger applications, since you don't have to worry about a caller forgetting to `if ! fn` or `fn ||` (and terminating the script if `set -e`). It also makes it easier to communicate specific error codes and helps separate between calculated / expected errors and unexpected errors (fatal / faults)
+It can look redundant (compared to `if ! fn; then :; fi`) to define error functions, but it can help make errors a bit more safe in larger applications, since you don't have to worry about a caller forgetting to `if ! fn` or `fn ||` (and terminating the script if `set -e`). It also makes it easier to communicate specific error codes and helps separate between calculated / expected errors and unexpected errors / faults
 
 - `core.err_set`
 - `core.err_clear`
 - `core.err_exists`
 
 ### `stacktrace`
 
-Prints the stack trace. Recommended to use with `core.trap_add`
+Prints the stack trace. It is recommended to use this with `core.trap_add` (see [example](./docs/api.md#corestacktraceprint))
 
 - `core.stacktrace_print`
 
+This is what it may look like
+
+```txt
+Stacktrace:
+  in core.stacktrace_print (/storage/ur/storage_home/Docs/Programming/repos/Groups/Bash/bash-core/.hidden/test.sh:0)
+  in err_handler (/storage/ur/storage_home/Docs/Programming/repos/Groups/Bash/bash-core/.hidden/test.sh:36)
+  in fn3 (/storage/ur/storage_home/Docs/Programming/repos/Groups/Bash/bash-core/.hidden/test.sh:48)
+  in fn2 (/storage/ur/storage_home/Docs/Programming/repos/Groups/Bash/bash-core/.hidden/test.sh:53)
+  in fn (/storage/ur/storage_home/Docs/Programming/repos/Groups/Bash/bash-core/.hidden/test.sh:57)
+```
+
 ## Installation
 
 Use [Basalt](https://github.com/hyperupcall/basalt), a Bash package manager, to add this project as a dependency

docs/api.md

@@ -18,8 +18,7 @@ Core functions for any Bash program
 
 ### core.init()
 
-Initiates global variables used by other functions
-@deprecated
+(DEPRECATED) Initiates global variables used by other functions. Deprecated as this function is called automatically
 
 _Function has no arguments._
 

pkg/src/public/bash-core.sh

@@ -3,8 +3,7 @@
 # @name bash-core
 # @description Core functions for any Bash program
 
-# @description Initiates global variables used by other functions
-# @deprecated
+# @description (DEPRECATED) Initiates global variables used by other functions. Deprecated as this function is called automatically
 # @noargs
 core.init() {
 	core.util.init

pkg/src/util/util.sh

@@ -1,5 +1,6 @@
 # shellcheck shell=bash
 
+# @internal
 core.util.init() {
 	if [ ${___global_bash_core_has_init__+x} ]; then
 		return
@@ -10,6 +11,7 @@ core.util.init() {
 	declare -ga ___global_shopt_stack___=()
 }
 
+# @internal
 core.util.trap_handler_common() {
 	local signal_spec="$1"
 

tests/trap.bats

@@ -2,12 +2,15 @@
 
 load './util/init.sh'
 
-# Note that this and similar functions only test for array appending, not
-# actual execution of the functions on the signal. There seems to be a limitation
+# Note that the array appending of these core.trap-* functions are tested. The actual
+# execution of the functions on the signal are bit tested. There seems to be a limitation
 # of Bats that prevents this from working
 
-# The '${___global_trap_table___[nokey]}' is there to ensure that the
-# ___global_trap_table___ is an actual associative array. If '___global_trap_table___' is not an associative array, the index with 'nokey' still returns the value of the variable (no error will be thrown). These were origianlly done when the 'core.init' function was not called within these tests
+# Additionally, the '${___global_trap_table___[nokey]}' is there to ensure that the
+# ___global_trap_table___ is an associative array. If that variable is not an associative
+# array, indexing with 'nokey' still yields the value of the (string) variable (no error
+# will be thrown). Now that 'core.init' is automatically called when the array is not
+# defined (to be an associative array), these checks are unecessary (yet, they still exist)
 
 @test "core.trap_add fails when function is not supplied" {
 	run core.trap_add '' 'USR1'