add documentation inside the shell scripts

Author: jrodolfo

scripts/build-all.sh

@@ -1,9 +1,31 @@
 #!/usr/bin/env bash
+#
+# build-all.sh
+#
+# Purpose:
+#   Orchestrates the build process for all components: solace-broker-api,
+#   solace-publisher-ui, and solace-subscriber.
+#
+# Usage:
+#   ./build-all.sh
+#
+# Required tools/dependencies:
+#   - bash
+#   - Tools required by individual build scripts (e.g., mvn, npm).
+#
+# Expected output:
+#   Logs from individual build scripts and a final confirmation message.
+#
+# Exit behavior:
+#   Exits with code 0 on success.
+#   Exits with a non-zero code if any individual build fails.
 
 set -euo pipefail
 
+# Directory where this script is located.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# Trigger builds for all components.
 "${SCRIPT_DIR}/build-broker-api.sh"
 "${SCRIPT_DIR}/build-publisher-ui.sh"
 "${SCRIPT_DIR}/build-subscriber.sh"

scripts/build-broker-api.sh

@@ -1,13 +1,37 @@
 #!/usr/bin/env bash
+#
+# build-broker-api.sh
+#
+# Purpose:
+#   Builds the solace-broker-api Java component using Maven.
+#
+# Usage:
+#   ./build-broker-api.sh
+#
+# Required tools/dependencies:
+#   - bash
+#   - java
+#   - mvn
+#
+# Expected output:
+#   Maven build logs and a final package in the target directory.
+#
+# Exit behavior:
+#   Exits with code 0 on success.
+#   Exits with a non-zero code if the Maven build fails.
 
 set -euo pipefail
 
+# Source common utility functions.
 source "$(cd "$(dirname "$0")" && pwd)/common.sh"
 
+# Ensure required commands are available.
 require_command java
 require_command mvn
 
+# Navigate to the component directory.
 enter_module "solace-broker-api"
 
 echo "building solace-broker-api"
+# Execute maven build.
 exec mvn clean package

scripts/build-publisher-ui.sh

@@ -1,20 +1,47 @@
 #!/usr/bin/env bash
+#
+# build-publisher-ui.sh
+#
+# Purpose:
+#   Builds the solace-publisher-ui component using npm.
+#   Installs dependencies if node_modules is missing.
+#
+# Usage:
+#   ./build-publisher-ui.sh
+#
+# Required tools/dependencies:
+#   - bash
+#   - node
+#   - npm
+#
+# Expected output:
+#   npm install logs (if needed), npm build logs, and a production build in the dist folder.
+#
+# Exit behavior:
+#   Exits with code 0 on success.
+#   Exits with a non-zero code if dependencies installation or build fails.
 
 set -euo pipefail
 
+# Source common utility functions.
 source "$(cd "$(dirname "$0")" && pwd)/common.sh"
 
+# Ensure required commands are available.
 require_command node
 require_command npm
 
+# Use environment variable for module directory or default to solace-publisher-ui.
 PUBLISHER_UI_DIR="${PUBLISHER_UI_DIR:-solace-publisher-ui}"
 
+# Navigate to the component directory.
 enter_module "${PUBLISHER_UI_DIR}"
 
+# Check for dependencies and install them if they are missing.
 if [[ ! -d node_modules ]]; then
   echo "node_modules is missing in ${PUBLISHER_UI_DIR}; running 'npm install' first"
   npm install
 fi
 
 echo "building solace-publisher-ui"
+# Execute npm build.
 exec npm run build

scripts/build-subscriber.sh

@@ -1,13 +1,37 @@
 #!/usr/bin/env bash
+#
+# build-subscriber.sh
+#
+# Purpose:
+#   Builds the solace-subscriber Java component using Maven.
+#
+# Usage:
+#   ./build-subscriber.sh
+#
+# Required tools/dependencies:
+#   - bash
+#   - java
+#   - mvn
+#
+# Expected output:
+#   Maven build logs and a final package in the target directory.
+#
+# Exit behavior:
+#   Exits with code 0 on success.
+#   Exits with a non-zero code if the Maven build fails.
 
 set -euo pipefail
 
+# Source common utility functions.
 source "$(cd "$(dirname "$0")" && pwd)/common.sh"
 
+# Ensure required commands are available.
 require_command java
 require_command mvn
 
+# Navigate to the component directory.
 enter_module "solace-subscriber"
 
 echo "building solace-subscriber"
+# Execute maven build.
 exec mvn clean package

scripts/common.sh

@@ -1,9 +1,35 @@
 #!/usr/bin/env bash
+#
+# common.sh
+#
+# Purpose:
+#   Provides shared utility functions for all scripts in the repository.
+#
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+#
+# Required tools/dependencies:
+#   - bash
+#
+# Expected output:
+#   None (defines functions for other scripts).
+#
+# Exit behavior:
+#   The utility functions may exit the script with code 1 if requirements are not met.
 
 set -euo pipefail
 
+# The root directory of the repository, calculated relative to this script's location.
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
+# Function: require_command
+# Purpose: Checks if a command exists in the PATH.
+# Inputs:
+#   $1 - The name of the command to check.
+# Outputs:
+#   Prints an error message to stderr if the command is missing.
+# Exit behavior:
+#   Exits with code 1 if the command is not found.
 require_command() {
   local command_name="$1"
   if ! command -v "${command_name}" >/dev/null 2>&1; then
@@ -12,6 +38,14 @@ require_command() {
   fi
 }
 
+# Function: require_env_var
+# Purpose: Checks if an environment variable is set and non-empty.
+# Inputs:
+#   $1 - The name of the environment variable to check.
+# Outputs:
+#   Prints an error message to stderr if the variable is missing.
+# Exit behavior:
+#   Exits with code 1 if the variable is not set or empty.
 require_env_var() {
   local variable_name="$1"
   if [[ -z "${!variable_name:-}" ]]; then
@@ -20,6 +54,14 @@ require_env_var() {
   fi
 }
 
+# Function: require_solace_env_vars
+# Purpose: Validates that all required Solace Cloud environment variables are set.
+# Inputs:
+#   $1 - (Optional) Name of the caller script for logging purposes.
+# Outputs:
+#   Prints error messages to stderr listing the missing variables.
+# Exit behavior:
+#   Exits with code 1 if any required Solace variable is missing.
 require_solace_env_vars() {
   local caller_name="${1:-this script}"
   local required_vars=(
@@ -43,6 +85,14 @@ require_solace_env_vars() {
   done
 }
 
+# Function: enter_module
+# Purpose: Changes the current working directory to a specific module.
+# Inputs:
+#   $1 - The path to the module (absolute or relative to REPO_ROOT).
+# Outputs:
+#   None.
+# Exit behavior:
+#   Returns or exits if 'cd' fails (due to 'set -e').
 enter_module() {
   local module_path="$1"
   if [[ "${module_path}" = /* ]]; then

scripts/restart-all.sh

@@ -1,21 +1,50 @@
 #!/usr/bin/env bash
+#
+# restart-all.sh
+#
+# Purpose:
+#   Restarts the entire workspace by stopping, rebuilding, and starting all components.
+#
+# Usage:
+#   ./restart-all.sh
+#
+# Required tools/dependencies:
+#   - bash
+#   - Individual component build and run dependencies.
+#
+# Expected output:
+#   Console output from stop, build, and start scripts with separators.
+#
+# Exit behavior:
+#   Exits with code 0 on success.
+#   Exits with a non-zero code if any sub-script fails.
 
 set -euo pipefail
 
+# Directory where this script is located.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# Function: print_separator
+# Purpose: Prints a formatted separator line with a label for better log readability.
+# Inputs:
+#   $1 - The label to display in the separator.
+# Outputs:
+#   A formatted string to stdout.
 print_separator() {
   local label="$1"
   echo
   printf '==================== %s ====================\n' "${label}"
   echo
 }
 
+# Stop all running components.
 print_separator "stopping workspace"
 "${SCRIPT_DIR}/stop-all.sh"
 
+# Rebuild all components.
 print_separator "building workspace"
 "${SCRIPT_DIR}/build-all.sh"
 
+# Start all components.
 print_separator "starting workspace"
 "${SCRIPT_DIR}/start-all.sh"