[develop] Update description blocks for ush files (NOAA-EMC#4791)

When re-examining issue 299, there were several files in ush that were found
to have a missing documentation/descriptor block. This PR adds a
description block to several files, and also removes a file that appears
to be unused since GFSv15

Author: TravisElless-NOAA

ush/WAM_XML_to_ASCII.pl

@@ -1,4 +1,17 @@
 #!/usr/bin/env perl
+
+#===============================================================================
+#
+#  FILE: WAM_XML_to_ASCII.pl
+#
+#  DESCRIPTION: Parses space weather data (F10.7 and Kp indices) from an XML
+#               input file (wam_input2.xsd) and converts it into a formatted
+#               ASCII text file (wam_input.asc) suitable for downstream processing.
+#
+#  INPUT: wam_input2.xsd (Expected to contain 'issue-date',
+#        'f10-81-avg-currentday', and an array of 'data-item' nodes).
+#  OUTPUT: wam_input.asc (Formatted ASCII table containing 56 records of
+#          Date_Time, F10, Kp, F10Flag, and KpFlag).
 use strict;
 use warnings;
 

ush/atmos_ensstat.sh

@@ -1,5 +1,24 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: atmos_ensstat.sh
+#
+#   DESCRIPTION: This script processes ensemble forecast output for a specific
+#                grid and forecast hour. It collects atmospheric GRIB2 files
+#                for all ensemble members, dynamically generates a namelist,
+#                and executes `ensstat.x` to compute the ensemble mean and
+#                spread. Finally, it indexes the outputs using wgrib2, moves
+#                them to the designated COM directory, and issues DBN alerts.
+#    ARGUMENTS:
+#       $1 - grid      : The grid resolution/identifier (e.g., 0p25, 1p00).
+#       $2 - fhr3      : The 3-digit forecast hour (e.g., 012, 024).
+#       $3 - grid_type : (Optional) Grid type identifier (defaults to empty).
+#
+#       OUTPUTS:
+#       Produces mean and spread GRIB2 files and their corresponding .idx
+#       inventory files in the configured COMOUT directory.
+
 grid=${1}
 fhr3=${2}
 grid_type=${3:-''}

ush/forecast_det.sh

@@ -1,5 +1,15 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: forecast_det.sh
+#
+#   DESCRIPTION: Determines the run type (Cold Start, Warm Start, or Re-run)
+#                for the Unified Forecast System (UFS). It evaluates the
+#                availability of required restart files across all coupled model
+#                components and atmospheric initial conditions. Based on this availability, it sets the
+#                appropriate logical flags and environment variables to guide downstream model initialization.
+
 # Disable variable not used warnings
 # shellcheck disable=SC2034
 UFS_det() {

ush/forecast_postdet.sh

@@ -1,5 +1,16 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: forecast_postdet.sh
+#
+#   DESCRIPTION: A suite of handler functions for managing the data flow and
+#                configuration of various Unified Forecast System (UFS)
+#                coupled components. It handles the staging of initial conditions,
+#                namelist generation, and output/restart file management for:
+#                FV3 (Atmosphere), WW3 (Waves), MOM6 (Ocean), CICE (Sea Ice),
+#                GOCART (Aerosols), and CMEPS (Coupler/Mediator)
+
 # Disable variable not used warnings
 # shellcheck disable=SC2034
 # shellcheck disable=SC2178

ush/forecast_predet.sh

@@ -1,5 +1,16 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: forecast_predet.sh
+#
+#   DESCRIPTION: A library of utility functions for the Unified Forecast System (UFS).
+#                This script defines date/time calculation utilities and component-specific setup
+#                functions. These setup functions initialize environment variables, configure directory
+#                structures, establish temporal domains (e.g., forecast hours,
+#                output frequencies), and stage requisite static/fix files
+#                prior to the run-type determination (warm vs. cold start).
+
 to_seconds() {
     # Function to convert HHMMSS to seconds since 00Z
     local hhmmss hh mm ss seconds padded_seconds

ush/fv3gfs_remap_weights.sh

@@ -1,5 +1,21 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: getdump.sh
+#
+#   DESCRIPTION: This script copies observational data dump files from a source
+#                dump directory to a target runtime directory for a specific
+#                model run, cycle time, and component. It strictly requires the
+#                presence of the status file (updated.status.tm00.bufr_d) to
+#                ensure the dump is complete before initiating the copy process.
+#    ARGUMENTS:
+#       $1 - YMD        : Date of the cycle in YYYYMMDD format.
+#       $2 - HH         : Hour of the cycle (e.g., 00, 06, 12, 18).
+#       $3 - RUN        : Model run identifier (e.g., gfs, gdas).
+#       $4 - SOURCE_DIR : (Optional) Override for the source dump directory.
+#       $5 - TARGET_DIR : (Optional) Override for the target runtime directory.
+
 COMPONENT=${COMPONENT:-atmos}
 
 YMD=${1:-""}

ush/getdump.sh

@@ -1,5 +1,24 @@
 #! /usr/bin/env bash
 
+#===============================================================================
+#
+#   FILE: get_ioda.sh
+#
+#   DESCRIPTION: This script transfers multi-component observational data dumps
+#                (e.g., IODA files) from a source staging directory to the target
+#                model runtime directory. It dynamically loops through all
+#                available component subdirectories (e.g., atmos, ocean, land),
+#                verifies the presence of a completion status log (*status.log)
+#                for each component, and copies the relevant cycle-prefixed files.
+#
+#
+#    ARGUMENTS:
+#       $1 - YMD        : Date of the cycle in YYYYMMDD format.
+#       $2 - HH         : Hour of the cycle (e.g., 00, 06, 12, 18).
+#       $3 - RUN        : Model run identifier (e.g., gfs, gdas).
+#       $4 - SOURCE_DIR : (Optional) Override for the source IODA dump directory.
+#       $5 - TARGET_DIR : (Optional) Override for the target runtime directory.
+
 YMD=${1:-""}
 HH=${2:-""}
 RUN=${3:-""}

ush/getioda.sh

@@ -1,5 +1,14 @@
 #! /usr/bin/env bash
-
+#===============================================================================
+#
+#   FILE: make_tif.sh
+#
+#   DESCRIPTION: This script converts an input GIF graphic into a TIF format
+#                using ImageMagick. If configured, it then prepends a standard
+#                NOAA Telecommunications (NTC) header (WMO: QTUA11, ORIG: KWBC)
+#                using a Perl utility. Finally, it copies the formatted file to
+#                the operational WMO COM directory and issues a DBN alert for
+#                downstream distribution.
 cd "${DATA}" || exit 2
 
 outname=out.tif

ush/make_tif.sh

@@ -1,4 +1,16 @@
 #!/bin/bash
+
+#===============================================================================
+#
+#   FILE: module-setup.sh
+#
+#   DESCRIPTION: This script initializes the environment module system (e.g., Lmod)
+#                and establishes a clean baseline by purging or resetting currently
+#                loaded modules. It dynamically adapts to the host machine by
+#                sourcing a detection script and applying the correct initialization
+#                paths and default module parameters for various supported HPC
+#                and cloud platforms.
+
 set -u
 
 source "${HOMEglobal}/ush/detect_machine.sh"