chore: add docstrings to feat/dfm (#84)

Docstrings generation was requested by @ivuorinen.

* https://github.com/ivuorinen/dotfiles/pull/59#issuecomment-2564381679

The following files were modified:

* `local/dfm/cmd/install.sh`
* `local/dfm/lib/common.sh`
* `local/dfm/lib/utils.sh`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

local/dfm/cmd/install.sh

@@ -4,7 +4,27 @@
 # @author Ismo Vuorinen <https://github.com/ivuorinen>
 # @license MIT
 
-# @description Install all packages in the correct order
+# Installs all required packages in the correct order.
+#
+# Description:
+#   Orchestrates the installation process for the dotfile manager by sequentially invoking
+#   the installation routines for fonts, Homebrew, and Rust (cargo). It logs the start of the 
+#   overall installation process before calling each respective function.
+#
+# Globals:
+#   lib::log - Function used to log installation progress messages.
+#
+# Arguments:
+#   None.
+#
+# Outputs:
+#   Logs an informational message indicating the start of the installation process.
+#
+# Returns:
+#   None.
+#
+# Example:
+#   all
 function all()
 {
   lib::log "Installing all packages..."
@@ -13,7 +33,22 @@ function all()
   cargo
 }
 
-# @description Install fonts
+# Installs fonts required by the dotfile manager.
+#
+# Globals:
+#   None.
+#
+# Arguments:
+#   None.
+#
+# Outputs:
+#   Logs a message to STDOUT indicating that the font installation process has started.
+#
+# Returns:
+#   None.
+#
+# Example:
+#   fonts
 function fonts()
 {
   lib::log "Installing fonts..."
@@ -22,14 +57,33 @@ function fonts()
 
 # Install Homebrew and set it up.
 #
-# @description Installs Homebrew
+# Installs the Homebrew package manager on macOS.
+#
+# Globals:
+#   lib::log - Logging utility used to report installation progress.
+#
+# Outputs:
+#   Logs a message indicating the start of the Homebrew installation process.
+#
+# Example:
+#   brew
 function brew()
 {
   lib::log "Installing Homebrew..."
   # implement Homebrew installation
 }
 
-# @description Install Rust and cargo packages.
+# Installs Rust and cargo packages.
+#
+# Description:
+#   Logs the start of the installation process for Rust and cargo packages.
+#   The installation logic is intended to be implemented where indicated.
+#
+# Globals:
+#   Uses lib::log for logging the installation process.
+#
+# Example:
+#   cargo
 function cargo()
 {
   lib::log "Installing Rust and cargo packages..."

local/dfm/lib/common.sh

@@ -29,7 +29,20 @@ LOG_LEVEL="${LOG_LEVEL:-INFO}"
 #
 # @description Log a message to the console
 # @param $* Message to log
-# @return void
+# Logs a message with a timestamp.
+#
+# Description:
+#   Outputs the provided message(s) to standard output, prepended with the current date and
+#   time in the format [YYYY-MM-DD HH:MM:SS]. This timestamp helps in tracking log events.
+#
+# Arguments:
+#   One or more strings that form the log message.
+#
+# Outputs:
+#   Writes the timestamped log message to standard output.
+#
+# Example:
+#   lib::log "Server started"   # Outputs: [2025-02-28 09:45:00] Server started
 lib::log()
 {
   printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*"
@@ -42,7 +55,19 @@ lib::log()
 #
 # @description Log an error message to the console
 # @param $* Error message
-# @return void
+# Logs an error message with a timestamp to standard error.
+#
+# This function formats the provided message(s) by prefixing it with the current date
+# and time along with an "ERROR:" label, then outputs the result to STDERR.
+#
+# Arguments:
+#   $* - The error message or messages to be logged.
+#
+# Outputs:
+#   Writes the formatted error message to STDERR.
+#
+# Example:
+#   lib::error "Failed to read the configuration file."
 lib::error()
 {
   printf '[%s] ERROR: %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >&2
@@ -57,7 +82,30 @@ lib::error()
 # @description Handle an error
 # @param $1 Line number
 # @param $2 Command
-# @return void
+# Logs an error message based on the previous command's exit code and the provided context.
+#
+# This function captures the exit code from the last executed command and, using the provided
+# line number and command string, determines the appropriate error message to log based on
+# predefined error codes stored in the ERROR_CODES associative array.
+#
+# Globals:
+#   ERROR_CODES - An associative array mapping error code names to numeric values.
+#   lib::error  - Logs error messages to STDERR.
+#
+# Arguments:
+#   line_no  - The line number in the script where the error occurred.
+#   command  - The command that was executed when the error occurred.
+#
+# Outputs:
+#   Writes a descriptive error message to STDERR.
+#
+# Returns:
+#   The exit code of the failed command.
+#
+# Example:
+#   # If a command fails with an exit code corresponding to an invalid argument:
+#   lib::error::handle 42 "some_command"
+#   # This logs: "Invalid argument at line 42 in command 'some_command'" (if the exit code matches ERROR_CODES[INVALID_ARGUMENT])
 lib::error::handle()
 {
   local exit_code=$?
@@ -99,7 +147,23 @@ lib::error::handle()
 # @description Throw an error
 # @param $1 Error code name
 # @param $* Error message
-# @return void
+# Logs an error message and terminates the script by performing cleanup with a specified error code.
+#
+# Globals:
+#   ERROR_CODES - Associative array mapping error code names to numeric exit values.
+#
+# Arguments:
+#   code_name - The key to retrieve the error code from the ERROR_CODES array.
+#   message   - The error message to log, constructed from all subsequent arguments.
+#
+# Outputs:
+#   Logs the error message to standard error.
+#
+# Returns:
+#   Exits the script via the cleanup function; does not return.
+#
+# Example:
+#   lib::error::throw "FILE_NOT_FOUND" "Required file not found: /path/to/file"
 lib::error::throw()
 {
   local code_name=$1
@@ -125,7 +189,21 @@ lib::error::throw()
 # @description Log a message to the console based on the log level setting.
 # @param $1 Log level
 # @param $2 Message
-# @return void
+# Logs a message if its severity meets or exceeds the global log level.
+#
+# Globals:
+#   LOG_LEVELS - Associative array mapping log level names to severity values.
+#   LOG_LEVEL  - The current log level threshold.
+#
+# Arguments:
+#   level: A string representing the log severity (e.g., DEBUG, INFO, WARN, ERROR).
+#   msg:   The message to log.
+#
+# Outputs:
+#   Prints a formatted log message with a timestamp to STDERR when the specified level qualifies.
+#
+# Example:
+#   logger::log INFO "Initialization complete"
 logger::log()
 {
   local level=$1
@@ -146,7 +224,14 @@ logger::log()
 #
 # @description Log a debug message to the console
 # @param $* Message
-# @return void
+# Logs a debug-level message.
+#
+# This function logs a message at the DEBUG level by delegating to logger::log.
+# It accepts one or more arguments that form the debug message, which are passed along
+# to the underlying logger::log function.
+#
+# Example:
+#   logger::debug "Debug info for variable x:" "$x"
 logger::debug()
 {
   logger::log "DEBUG" "$@"
@@ -161,7 +246,20 @@ logger::debug()
 #
 # @description Log an info message to the console
 # @param $* Message
-# @return void
+# Logs an informational message to the console.
+#
+# Description:
+#   This function wraps the logger::log function to log messages at the "INFO" level. All provided arguments are
+#   forwarded to logger::log, where the message is formatted and output based on the current logging configuration.
+#
+# Arguments:
+#   A message string followed by optional additional parameters used to format the message.
+#
+# Outputs:
+#   The formatted informational message is written to STDOUT if the INFO log level is enabled.
+#
+# Example:
+#   logger::info "Service started successfully on port" 8080
 logger::info()
 {
   logger::log "INFO" "$@"
@@ -176,7 +274,19 @@ logger::info()
 #
 # @description Log a warning message to the console
 # @param $* Message
-# @return void
+# Logs a warning message.
+#
+# This function acts as a wrapper around `logger::log` by setting the log level to "WARN"
+# for all provided message arguments. It forwards the given messages to the logger for output.
+#
+# Arguments:
+#   A variable list of strings representing the warning message.
+#
+# Outputs:
+#   Writes a formatted warning message to the console.
+#
+# Example:
+#   logger::warn "Low disk space" "Free up some space to avoid issues"
 logger::warn()
 {
   logger::log "WARN" "$@"
@@ -191,7 +301,16 @@ logger::warn()
 #
 # @description Log an error message to the console
 # @param $* Message
-# @return void
+# Logs an error message at the ERROR level.
+#
+# This function wraps the generic logging mechanism to record error messages by automatically
+# specifying the ERROR severity level. It passes all provided arguments to the underlying logging function.
+#
+# Arguments:
+#   Error message(s) – One or more strings that describe the error.
+#
+# Example:
+#   logger::error "Unable to open file" "/path/to/file"
 logger::error()
 {
   logger::log "ERROR" "$@"
@@ -202,7 +321,16 @@ logger::error()
 # The function is registered with the `EXIT` trap.
 #
 # @description Remove temporary files and directories
-# @return void
+# Cleans up temporary resources before exiting.
+#
+# Globals:
+#   TEMP_DIR - Path to the temporary directory to be removed if it exists.
+#
+# Returns:
+#   Exits the script with the original exit code.
+#
+# Example:
+#   trap cleanup EXIT
 cleanup()
 {
   local exit_code=$?
@@ -225,7 +353,22 @@ trap cleanup EXIT
 #
 # @description Handle an error
 # @param $1 Line number
-# @return void
+# Handles an error event by logging the line number and corresponding exit code.
+#
+# Globals:
+#   $? - The exit code of the last executed command.
+#
+# Arguments:
+#   $1 - The line number where the error occurred.
+#
+# Outputs:
+#   Logs an error message to STDERR via logger::error.
+#
+# Returns:
+#   None
+#
+# Example:
+#   handle_error ${LINENO}
 handle_error()
 {
   local exit_code=$?

local/dfm/lib/utils.sh

@@ -23,53 +23,220 @@ readonly MAGENTA="\033[35m"
 readonly CYAN="\033[36m"
 readonly WHITE="\033[37m"
 
+# Prints the provided text in black color using ANSI escape codes.
+#
+# Globals:
+#   BLACK - ANSI escape code for black text.
+#   RESET - ANSI escape code to reset terminal formatting.
+#
+# Arguments:
+#   One or more strings that will be concatenated and printed.
+#
+# Outputs:
+#   Writes the colored text to STDOUT (without a trailing newline).
+#
+# Example:
+#   clr::black "This text will appear in black."
 clr::black()
 {
   printf "${BLACK}%s${RESET}" "$*"
 }
+# Prints the provided text in red using ANSI escape codes.
+#
+# Globals:
+#   RED    - ANSI escape code for red.
+#   RESET  - ANSI escape code to reset terminal formatting.
+#
+# Arguments:
+#   One or more strings that will be printed in red.
+#
+# Outputs:
+#   Writes the red formatted text to STDOUT.
+#
+# Example:
+#   clr::red "Error: Invalid input"
 clr::red()
 {
   printf "${RED}%s${RESET}" "$*"
 }
+# Prints the given text in green using ANSI escape codes.
+#
+# Arguments:
+#   * One or more strings to output in green. Multiple arguments are concatenated.
+#
+# Outputs:
+#   Writes the formatted green text to STDOUT without a trailing newline.
+#
+# Example:
+#   clr::green "Operation successful"
 clr::green()
 {
   printf "${GREEN}%s${RESET}" "$*"
 }
+# Prints the provided text in yellow color.
+#
+# Globals:
+#   YELLOW - ANSI escape code for yellow text.
+#   RESET  - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   Any text passed as parameters will be printed in yellow.
+#
+# Outputs:
+#   Colored text printed to STDOUT.
+#
+# Example:
+#   clr::yellow "Hello, World!"
 clr::yellow()
 {
   printf "${YELLOW}%s${RESET}" "$*"
 }
+# Prints the provided text in blue using ANSI escape codes.
+#
+# Globals:
+#   BLUE    ANSI escape sequence for blue text.
+#   RESET   ANSI escape sequence to reset text formatting.
+#
+# Arguments:
+#   $@      One or more strings to be printed in blue.
+#
+# Outputs:
+#   Prints the input text in blue to STDOUT.
+#
+# Example:
+#   clr::blue "Hello, World!"
 clr::blue()
 {
   printf "${BLUE}%s${RESET}" "$*"
 }
+# Prints the provided text in magenta color.
+#
+# This function outputs one or more strings wrapped in ANSI escape sequences
+# to display them in magenta. It uses the global variables MAGENTA for the color
+# and RESET to revert to the default formatting.
+#
+# Globals:
+#   MAGENTA - ANSI escape sequence for magenta.
+#   RESET   - ANSI escape code to reset formatting.
+#
+# Arguments:
+#   One or more strings to print in magenta.
+#
+# Outputs:
+#   Writes the formatted string directly to STDOUT.
+#
+# Example:
+#   clr::magenta "Hello, World!"
 clr::magenta()
 {
   printf "${MAGENTA}%s${RESET}" "$*"
 }
+# Prints the provided text in white color using ANSI escape codes.
+#
+# Globals:
+#   WHITE - ANSI escape code for white.
+#   RESET - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   Any text passed as arguments will be concatenated and printed.
+#
+# Outputs:
+#   Writes the formatted text to STDOUT.
+#
+# Example:
+#   clr::white "Hello, World!"
 clr::white()
 {
   printf "${WHITE}%s${RESET}" "$*"
 }
 
+# Applies bold styling to the provided text and prints it to STDOUT.
+#
+# Globals:
+#   BOLD  - ANSI escape code for enabling bold text.
+#   RESET - ANSI escape code for resetting text formatting.
+#
+# Arguments:
+#   One or more strings to be printed in bold.
+#
+# Outputs:
+#   Bold-formatted text is printed to STDOUT.
+#
+# Example:
+#   style::bold "This is bold text"
 style::bold()
 {
   printf "${BOLD}%s${RESET}" "$*"
 }
+# Print the provided text in a dim style using ANSI escape codes.
+#
+# Globals:
+#   DIM   - ANSI escape code for applying dim styling.
+#   RESET - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   $* - The text to be printed in dim style.
+#
+# Outputs:
+#   Writes the formatted dim text to STDOUT.
+#
+# Example:
+#   style::dim "This text will appear dimmed"
 style::dim()
 {
   printf "${DIM}%s${RESET}" "$*"
 }
+# Prints the provided text in italic style using ANSI escape sequences.
+#
+# Globals:
+#   ITALIC - ANSI escape sequence for italic text styling.
+#   RESET  - ANSI escape sequence to reset text styling.
+#
+# Arguments:
+#   All passed arguments are combined and printed in italic formatting.
+#
+# Outputs:
+#   The styled text is printed to STDOUT without an automatic newline.
+#
+# Example:
+#   style::italic "Hello, world!"
 style::italic()
 {
   printf "${ITALIC}%s${RESET}" "$*"
 }
+# Underlines the provided text using ANSI escape codes.
+#
+# Globals:
+#   UNDERLINE - ANSI escape sequence to start underlining.
+#   RESET     - ANSI escape sequence to reset text formatting.
+#
+# Arguments:
+#   $* - The text to be underlined.
+#
+# Outputs:
+#   Prints the underlined text to STDOUT.
+#
+# Example:
+#   style::underline "Underlined text"
 style::underline()
 {
   printf "${UNDERLINE}%s${RESET}" "$*"
 }
 
-# Function to print formatted line
+# Prints a formatted line to STDOUT using the provided format string and arguments.
+#
+# Globals:
+#   RESET - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   $1 - A format string that may include ANSI styling codes (do not include a conversion specifier for the text).
+#   $@ - The text to be formatted and printed.
+#
+# Outputs:
+#   Writes the formatted text to STDOUT with an appended newline, ensuring that styling is reset afterward.
+#
+# Example:
+#   list::print_formatted "${BOLD}" "Bold Text"
 list::print_formatted()
 {
   local format=$1
@@ -77,21 +244,65 @@ list::print_formatted()
   printf "${format}%s${RESET}\n" "$@"
 }
 
-# Function to print a header
+# Prints a formatted header with a decorative underline.
+#
+# Globals:
+#   BOLD   - ANSI escape code for bold text.
+#   BLUE   - ANSI escape code for blue text.
+#   RESET  - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   $1 - The header title to be displayed.
+#
+# Outputs:
+#   Writes a styled header to STDOUT, including the title in bold blue and a subsequent decorative line.
+#
+# Example:
+#   list::print_header "Available Commands"
 list::print_header()
 {
   printf "\n  ${BOLD}${BLUE}%s${RESET}\n" "$1"
   printf "%s\n" "  $(printf '%.s─' {1..60})"
 }
 
-# Function to print a group header
+# Prints a group header with bold yellow formatting.
+#
+# Globals:
+#   YELLOW - ANSI escape code for yellow color.
+#   BOLD   - ANSI escape code for bold text.
+#   RESET  - ANSI escape code to reset text formatting.
+#
+# Arguments:
+#   group  - The title text to display as the group header.
+#
+# Outputs:
+#   Writes the formatted group header to STDOUT.
+#
+# Example:
+#   list::print_group "My Group"
 list::print_group()
 {
   local group=$1
   printf "\n  ${YELLOW}${BOLD}%s${RESET}\n\n" "$group"
 }
 
-# Function to print a command
+# Prints a formatted command with an optional description.
+#
+# Globals:
+#   BOLD   - ANSI escape sequence for bold text.
+#   CYAN   - ANSI escape sequence for cyan text.
+#   RESET  - ANSI escape sequence to reset text formatting.
+#   DIM    - ANSI escape sequence for dim text.
+#
+# Arguments:
+#   cmd    - The command name to display.
+#   desc   - Optional description of the command (defaults to an empty string).
+#
+# Outputs:
+#   Writes the formatted command and description to STDOUT.
+#
+# Example:
+#   list::print_command "ls" "List directory contents"
 list::print_command()
 {
   local cmd=$1
@@ -99,7 +310,25 @@ list::print_command()
   printf "  ${BOLD}${CYAN}%-15s${RESET} ${DIM}%s${RESET}\n" "$cmd" "$desc"
 }
 
-# Function to print a subcommand
+# Prints a subcommand in a formatted style.
+#
+# This function displays a subcommand name in green with a fixed width for neat alignment,
+# followed by an optional description text. The ANSI escape codes for green text and reset
+# styling are used to highlight the subcommand.
+#
+# Globals:
+#   GREEN  - ANSI escape code applied to the subcommand name.
+#   RESET  - ANSI escape code used to reset text formatting.
+#
+# Arguments:
+#   cmd   - The subcommand name to print.
+#   desc  - (Optional) A description string for the subcommand. Defaults to empty if not provided.
+#
+# Outputs:
+#   Prints the formatted subcommand and optional description to STDOUT.
+#
+# Example:
+#   list::print_subcommand "deploy" "Deploy the application to the production server"
 list::print_subcommand()
 {
   local cmd=$1
@@ -107,6 +336,20 @@ list::print_subcommand()
   printf "    ${GREEN}%-13s${RESET} ${desc}\n" "$cmd"
 }
 
+# Iterates over functions defined in a command file and prints each as a formatted subcommand.
+#
+# This function reads function names from the specified command file, retrieves their descriptions
+# (removing any '@description' prefix), and prints each function name as a bullet point with its
+# associated description if available.
+#
+# Arguments:
+#   cmd_file - The path to the command file containing function definitions.
+#
+# Outputs:
+#   Prints formatted subcommand entries to STDOUT.
+#
+# Example:
+#   list::loop_functions "/path/to/command_file.sh"
 list::loop_functions()
 {
   local cmd_file="$1"
@@ -126,7 +369,23 @@ list::loop_functions()
   done < <(main::get_command_functions "$cmd_file")
 }
 
-# Get the documentation for a function from a command file.
+# Extracts and prints the documentation associated with a specific function from a command file.
+#
+# Globals:
+#   None
+#
+# Arguments:
+#   cmd_file - The file containing function definitions and their associated documentation.
+#   func     - The name of the function whose documentation should be extracted.
+#
+# Outputs:
+#   Writes the extracted documentation tags and their content to STDOUT.
+#
+# Returns:
+#   None
+#
+# Example:
+#   list::get_function_docs "commands.sh" "build_project"
 list::get_function_docs()
 {
   local cmd_file="$1"
@@ -173,7 +432,16 @@ list::get_function_docs()
 #
 # @description Check if a command exists
 # @param $1 Command to check
-# @return 0 if the command exists, 1 otherwise
+# Checks if a specified command is available in the system.
+#
+# Arguments:
+#   $1 - Command name to check.
+#
+# Returns:
+#   0 if the command is found in the system's PATH, 1 otherwise.
+#
+# Example:
+#   utils::is_installed "git" && echo "Git is installed" || echo "Git is not installed"
 utils::is_installed()
 {
   command -v "$1" > /dev/null 2>&1
@@ -191,7 +459,19 @@ utils::is_installed()
 #
 # @description Check if a directory is in PATH
 # @param $1 Directory to check
-# @return 0 if the directory is in PATH, 1 otherwise
+# Checks if a specified executable is available in one of the directories in the PATH.
+#
+# Globals:
+#   PATH - The system's PATH environment variable listing directories to search.
+#
+# Arguments:
+#   cmd: The name of the executable file to look for.
+#
+# Returns:
+#   0 if the executable is found in one of the PATH directories, 1 otherwise.
+#
+# Example:
+#   utils::in_path ls && echo "ls is available in PATH"
 utils::in_path()
 {
   local cmd=$1
@@ -220,7 +500,26 @@ utils::in_path()
 # @param $1 Maximum number of retries
 # @param $2.. Command to run
 # @return 0 if the command succeeds, 1 otherwise
-# @dependencies logger::warn
+# Retries a command until it succeeds or the maximum number of attempts is reached.
+#
+# Arguments:
+#   tries                   - Maximum number of attempts to execute the command.
+#   command and its args    - The command to run and any arguments to pass.
+#
+# Globals:
+#   logger::warn            - Logs a warning message for each failed attempt.
+#
+# Outputs:
+#   Warning messages are printed to STDERR for each retry.
+#
+# Returns:
+#   0 if the command eventually succeeds; 1 if all attempts fail.
+#
+# Example:
+#   utils::retry 3 my_command --option value
+#
+# Dependencies:
+#   logger::warn
 utils::retry()
 {
   local tries=$1
@@ -249,7 +548,25 @@ utils::retry()
 # @description Confirm an action
 # @param $1 Prompt message
 # @param $2 Default value
-# @return 0 if the user confirms, 1 otherwise
+# Prompts the user for confirmation with a yes/no question.
+#
+# Arguments:
+#   prompt: The message displayed to the user when asking for confirmation.
+#   default: An optional default answer used if no input is provided (defaults to "Y").
+#
+# Outputs:
+#   Repeatedly prompts the user until a valid yes or no answer is received.
+#   An error message is displayed for any invalid response.
+#
+# Returns:
+#   0 if the user confirms (answers yes), 1 if the user declines (answers no).
+#
+# Example:
+#   if utils::interactive::confirm "Do you want to proceed?"; then
+#       echo "Proceeding..."
+#   else
+#       echo "Operation cancelled."
+#   fi
 utils::interactive::confirm()
 {
   local prompt=$1
@@ -277,7 +594,17 @@ utils::interactive::confirm()
 # the cmd_files array. Finally, the function prints the array elements
 # separated by a space.
 #
-# @return A space-separated string of command files.
+# Finds all command script files (*.sh) in the directory specified by DFM_CMD_DIR.
+#
+# Globals:
+#   DFM_CMD_DIR - The directory to search for command files.
+#
+# Outputs:
+#   Echoes a space-separated list of command file paths.
+#
+# Example:
+#   files=$(main::find_commands)
+#   echo "$files"  # Displays the list of found command files.
 main::find_commands()
 {
   local cmd_files=()
@@ -294,7 +621,26 @@ main::find_commands()
 # line.
 #
 # @param cmd_file The command file to extract function names from.
-# @return A list of function names.
+# Extracts the names of functions defined in the specified command file.
+#
+# This function parses the provided file for Bash function definitions using
+# regex patterns matching both "function name() {" and "name() {" styles.
+# It outputs the names of the functions, one per line.
+#
+# Globals:
+#   None.
+#
+# Arguments:
+#   cmd_file - Path to the file containing Bash function definitions.
+#
+# Outputs:
+#   Writes the list of function names to STDOUT.
+#
+# Returns:
+#   A list of function names extracted from the file.
+#
+# Example:
+#   main::get_command_functions "/path/to/command_file.sh"
 main::get_command_functions()
 {
   local cmd_file="$1"
@@ -310,7 +656,21 @@ main::get_command_functions()
 #
 # @param cmd_file The command file to extract the function description from.
 # @param func The function name.
-# @return The function description.
+# Retrieves the annotated description of a specified function from a command file.
+#
+# This function searches the provided command file for an "@description" comment
+# preceding the definition of the designated function. It then extracts and prints
+# the description text. If no description is found, nothing is printed.
+#
+# Arguments:
+#   cmd_file - Path to the file containing the function definitions.
+#   func     - Name of the function whose description is to be extracted.
+#
+# Outputs:
+#   The extracted description text is printed to STDOUT.
+#
+# Example:
+#   desc=$(main::get_function_description "/path/to/commands.sh" "my_function")
 main::get_function_description()
 {
   local cmd_file="$1"
@@ -328,7 +688,24 @@ main::get_function_description()
 # It then iterates over the files and prints the command name and
 # its functions.
 #
-# @return None
+# Lists all available commands and their subcommands.
+#
+# Description:
+#   Uses main::find_commands to locate command files and prints a header followed by a group title.
+#   For each command file, extracts the command name (removing the '.sh' extension) and prints it,
+#   then calls list::loop_functions to display detailed subcommands.
+#
+# Globals:
+#   None.
+#
+# Arguments:
+#   None.
+#
+# Outputs:
+#   Writes the formatted list of commands and associated subcommands to STDOUT.
+#
+# Example:
+#   main::list_available_commands
 main::list_available_commands()
 {
   local cmd_files
@@ -354,7 +731,31 @@ main::list_available_commands()
 # @param cmd The command name.
 # @param func The function name.
 # @param args The function arguments.
-# @return None
+# Executes a specified function from a command file.
+#
+# This function validates and runs a function defined within a command file. It checks that both
+# the command and function names contain only allowed characters (alphanumeric, underscores, or dashes),
+# verifies that the command file (located in DFM_CMD_DIR) exists, is readable, and is free of syntax errors,
+# and then sources the file. If the specified function exists in the file, it is executed with any additional
+# arguments provided.
+#
+# Globals:
+#   DFM_CMD_DIR - Directory containing command files.
+#
+# Arguments:
+#   command: The command file name (without .sh extension) to execute. Must match ^[a-zA-Z0-9_-]+$.
+#   function: The function name to be executed from the command file. Must match ^[a-zA-Z0-9_-]+$.
+#   [additional arguments]: Extra parameters to pass to the executed function.
+#
+# Outputs:
+#   Any output generated by the executed function. Error messages are output via lib::error.
+#
+# Returns:
+#   0 if the function executes successfully; 1 if an error occurs (e.g., invalid names, missing or unreadable
+#   command file, syntax errors in the command file, or if the specified function is not found).
+#
+# Example:
+#   main::execute_command "deploy" "run_deploy" "arg1" "arg2"
 main::execute_command()
 {
   local cmd="$1"