From 0f8cb9faa33d0985e0ca6250e6842d821a9f3cde Mon Sep 17 00:00:00 2001
From: GeorgeGayno-NOAA <52789452+GeorgeGayno-NOAA@users.noreply.github.com>
Date: Thu, 20 Feb 2025 08:44:42 -0500
Subject: [PATCH] Fix Doxygen in global_cycle (#1026)

Add Doxygen definitions for two arguments in the "read_data" routine.

Add checks for missing optional argument LSOIL_INCR in "read_data".

Update the pull request template to always require a branch be compiled with
Doxygen before merging.

Fixes #1025.
---
 .github/PULL_REQUEST_TEMPLATE            |  5 +++++
 sorc/global_cycle.fd/read_write_data.f90 | 18 ++++++++++++++----
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE
index 1aee3fe56..717dac75b 100644
--- a/.github/PULL_REQUEST_TEMPLATE
+++ b/.github/PULL_REQUEST_TEMPLATE
@@ -19,6 +19,7 @@ If there are changes to the build or source code, the tests below must be conduc
 - [ ] Compile branch on all Tier 1 machines using Intel (Orion, Jet, Hera, Hercules and WCOSS2).
 - [ ] Compile branch on Hera using GNU.
 - [ ] Compile branch in 'Debug' mode on WCOSS2.
+- [ ] Compile with Doxygen on any machine with no errors.
 - [ ] Run unit tests locally on any Tier 1 machine.
 - [ ] Run relevant consistency tests locally on all Tier 1 machines.
 
@@ -34,6 +35,10 @@ Add any links to pending PRs that are required prior to merging this PR. For exa
 ufs-community/UFS_UTILS/pull/<pr_number>
 
 ## DOCUMENTATION:
+All new and updated source code must be documented with Doxygen.
+
+- [ ] Doxygen is updated.
+
 If this PR is contributing new capabilities that need to be documented, please also include updates to the RST files in the docs/source directory as supporting material.
 
 ## ISSUE: 
diff --git a/sorc/global_cycle.fd/read_write_data.f90 b/sorc/global_cycle.fd/read_write_data.f90
index 4eac568af..98a32f40d 100644
--- a/sorc/global_cycle.fd/read_write_data.f90
+++ b/sorc/global_cycle.fd/read_write_data.f90
@@ -1036,6 +1036,7 @@ END SUBROUTINE READ_GSI_DATA
  !! @param[in] LENSFC Total number of points on a tile.
  !! @param[in] DO_NSST When true, nsst fields are read.
  !! @param[out] IS_NOAHMP When true, process for the Noah-MP LSM.
+ !! @param[in] FNAME_INC Name of the increment file.
  !! @param[out] TSFFCS Skin Temperature.
  !! @param[out] SMCFCS Total volumetric soil moisture.
  !! @param[out] SWEFCS Snow water equivalent.
@@ -1076,6 +1077,7 @@ END SUBROUTINE READ_GSI_DATA
  !! @param[out] NSST Data structure containing nsst fields.
  !! @param[in] SLCINC Liquid soil moisture increments on the cubed-sphere tiles
  !! @param[in] STCINC Soil temperature increments on the cubed-sphere tiles
+ !! @param[in] LSOIL_INCR Number of soil layers (from top) to apply soil increments to
  !! @author George Gayno NOAA/EMC
  !! @author Yuan Xue: add capability to read soil related increments on the
  !! cubed-sphere tiles directly
@@ -1617,7 +1619,11 @@ SUBROUTINE READ_DATA(LSOIL,LENSFC,DO_NSST,IS_NOAHMP, &
  ELSE
      ! THIS IS A REGRIDDED GSI FILE
      IF (PRESENT(STCINC)) THEN
-     DO K = 1, LSOIL_INCR
+       IF (.NOT.PRESENT(LSOIL_INCR)) THEN
+         write(6,*)'FATAL ERROR variable lsoil_incr not declared.'
+         CALL MPI_ABORT(MPI_COMM_WORLD, 134, ERROR)
+       END IF
+       DO K = 1, LSOIL_INCR
          WRITE(K_CH, '(I1)') K
 
          INCVAR = "soilt"//K_CH//"_inc"
@@ -1628,10 +1634,14 @@ SUBROUTINE READ_DATA(LSOIL,LENSFC,DO_NSST,IS_NOAHMP, &
          CALL NETCDF_ERR(ERROR, 'READING soilt*_inc increments') 
 
          STCINC(:,K) = RESHAPE(dummy, (/LENSFC/))
-     ENDDO
+       ENDDO
      ENDIF
      IF (PRESENT(SLCINC)) THEN
-     DO K = 1, LSOIL_INCR
+       IF (.NOT.PRESENT(LSOIL_INCR)) THEN
+         write(6,*)'FATAL ERROR variable lsoil_incr not declared.'
+         CALL MPI_ABORT(MPI_COMM_WORLD, 136, ERROR)
+       END IF
+       DO K = 1, LSOIL_INCR
          WRITE(K_CH, '(I1)') K
 
          INCVAR = "slc"//K_CH//"_inc"
@@ -1642,7 +1652,7 @@ SUBROUTINE READ_DATA(LSOIL,LENSFC,DO_NSST,IS_NOAHMP, &
          CALL NETCDF_ERR(ERROR, 'READING slc*_inc increments') 
 
          SLCINC(:,K) = RESHAPE(dummy, (/LENSFC/))
-     ENDDO
+       ENDDO
      ENDIF
  ENDIF