Second round of major UPP documentation updates

docs/Doxyfile.in

@@ -1017,6 +1017,14 @@ FILTER_SOURCE_PATTERNS =
 
 USE_MDFILE_AS_MAINPAGE = @abs_top_srcdir@/docs/sp_user_guide.md
 
+# By default, all characters from position 72 are to be considered as comment.
+# This prevents Doxygen from recognizing certain variables as undocumented
+# because the variables are processed as comments.
+# Setting FORTRAN_COMMENT_AFTER to a larger value makes it possible to 
+# process longer lines before the automatic comment starts.
+
+FORTRAN_COMMENT_AFTER = 200
+
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
 #---------------------------------------------------------------------------

sorc/ncep_post.fd/CALHEL2.f

@@ -15,15 +15,15 @@
 !> 
 !> @param[in] LLOW Lower bound CAPE>=100 and CINS>=-250.
 !> @param[in] LUPP Upper bound CAPE< 100  or CINS< -250; allows one to distinguish 0-3 km and 0-1 km values.
-!> @param[in] DPTH Depth in meters over whcih helicity should be computed; allows one to distinguish 0-3 km and 0-1 km values.
+!> @param[in] DEPTH Depth in meters over whcih helicity should be computed; allows one to distinguish 0-3 km and 0-1 km values.
 !> @param[out] UST Estimated U Component (m/s) Of Storm motion.
 !> @param[out] VST Estimated V Component (m/s) Of Storm motion.
 !> @param[out] HELI Storm-relative heliciry (m**2/s**2).
 !> @param[out] CANGLE Critical angle.
-!> @param[out] USHR1 U Component (m/s) Of 0-1 km shear.
-!> @param[out] VSHR1 V Component (m/s) Of 0-1 km shear.
-!> @param[out] USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
-!> @param[out] VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @var USHR1 U Component (m/s) Of 0-1 km shear.
+!> @var VSHR1 V Component (m/s) Of 0-1 km shear.
+!> @var USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @var VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
 !>     
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -42,6 +42,18 @@
 !> 2021-09-02 | Bo Cui          | Decompose UPP in X direction          
 !>   
 !> @author Michael Baldwin W/NP2 @date 1994-08-22
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes storm relative helicity.
+!>
+!> @param[in] LLOW Lower bound CAPE>=100 and CINS>=-250.
+!> @param[in] LUPP Upper bound CAPE< 100  or CINS< -250; allows one to distinguish 0-3 km and 0-1 km values.
+!> @param[in] DEPTH Depth in meters over whcih helicity should be computed; allows one to distinguish 0-3 km and 0-1 km values.
+!> @param[out] UST Estimated U Component (m/s) Of Storm motion.
+!> @param[out] VST Estimated V Component (m/s) Of Storm motion.
+!> @param[out] HELI Storm-relative heliciry (m**2/s**2).
+!> @param[out] CANGLE Critical angle.
+!>     
+!-----------------------------------------------------------------------
       SUBROUTINE CALHEL2(LLOW,LUPP,DEPTH,UST,VST,HELI,CANGLE)
 
 !

sorc/ncep_post.fd/CALHEL3.f

@@ -2,7 +2,7 @@
 !> @brief Subroutine that computes storm relative helicity.
 !
 !> This routine computes estimated storm motion and storm-relative
-!> environmental helicity. (Davies-Jones et al 1990) the algorithm
+!> environmental helicity. (Davies-Jones, et al., 1990) the algorithm
 !> processd as follows.
 !>     
 !> The storm motion computation no longer employs the Davies and Johns (1993)
@@ -18,11 +18,11 @@
 !> @param[out] UST Estimated U Component (m/s) Of Storm motion.
 !> @param[out] VST Estimated V Component (m/s) Of Storm motion.
 !> @param[out] HELI Storm-relative heliciry (m**2/s**2).
-!> @param[out] CANGLE Critical angle.
-!> @param[out] USHR1 U Component (m/s) Of 0-1 km shear.
-!> @param[out] VSHR1 V Component (m/s) Of 0-1 km shear.
-!> @param[out] USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
-!> @param[out] VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @var CANGLE Critical angle.
+!> @var USHR1 U Component (m/s) Of 0-1 km shear.
+!> @var VSHR1 V Component (m/s) Of 0-1 km shear.
+!> @var USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @var VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
 !>     
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -43,6 +43,16 @@
 !> 2022-05-12 | E Colon         | Resolved a bug  which looped over the calculation of SRH at two fixed levels, erroneously doubling the magnitude.
 !>   
 !> @author Michael Baldwin W/NP2 @date 1994-08-22
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes storm relative helicity.
+!
+!> @param[in] LLOW Lower bound CAPE>=100 and CINS>=-250.
+!> @param[in] LUPP Upper bound CAPE< 100  or CINS< -250; allows one to distinguish 0-3 km and 0-1 km values.
+!> @param[out] UST Estimated U Component (m/s) Of Storm motion.
+!> @param[out] VST Estimated V Component (m/s) Of Storm motion.
+!> @param[out] HELI Storm-relative heliciry (m**2/s**2).
+!-----------------------------------------------------------------------
+
       SUBROUTINE CALHEL3(LLOW,LUPP,UST,VST,HELI)
 
 !

sorc/ncep_post.fd/CALLCL.f

@@ -28,6 +28,16 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>
 !> @author Russ Treadon W/NP2 @date 1993-03-15
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes the lifting condensation level (LCL) 
+!> height (above ground level) and pressure in each column at mass points.
+!>
+!> @param[in] P1D Array of parcel pressures (Pa).
+!> @param[in] T1D Array of parcel temperatures (K).
+!> @param[in] Q1D Array of parcel specific humidities (kg/kg).
+!> @param[out] PLCL Parcel Pressure at LCL (Pa).
+!> @param[out] ZLCL Parcel AGL height at LCL (m).
+!-----------------------------------------------------------------------
       SUBROUTINE CALLCL(P1D,T1D,Q1D,PLCL,ZLCL)
 
 !     

sorc/ncep_post.fd/CALMCVG.f

@@ -13,10 +13,10 @@
 !> moisture convergence which is returned by this routine.
 !></pre>
 !>   
-!> @param[in] Q1D      - Specific humidity at P-points (kg/kg).
-!> @param[in] U1D      - U wind component (m/s) at P-points.
-!> @param[in] V1D      - V wind component (m/s) at P-points.
-!> @param[out] QCNVG    - Moisture convergence (1/s) at P-points.
+!> @param[in] Q1D real Specific humidity at P-points (kg/kg).
+!> @param[in] U1D real U-wind component (m/s) at P-points.
+!> @param[in] V1D real V-wind component (m/s) at P-points.
+!> @param[out] QCNVG real Moisture convergence (1/s) at P-points.
 !>
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -32,6 +32,14 @@
 !> 2021-09-30 | J MENG       | 2D DECOMPOSITION
 !>     
 !> @author Russ Treadon W/NP2 @date 1993-01-22
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes moisture convergence.
+!>   
+!> @param[in] Q1D real Specific humidity at P-points (kg/kg).
+!> @param[in] U1D real U-wind component (m/s) at P-points.
+!> @param[in] V1D real V-wind component (m/s) at P-points.
+!> @param[out] QCNVG real Moisture convergence (1/s) at P-points.
+!-----------------------------------------------------------------------
       SUBROUTINE CALMCVG(Q1D,U1D,V1D,QCNVG)
 
 !

sorc/ncep_post.fd/CALPOT.f

@@ -18,6 +18,13 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>
 !> @author Russ Treadon W/NP2 @date 1992-12-24
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes potential temperature.
+!>
+!> @param[in] P1D pressures (Pa).
+!> @param[in] T1D temperatures (K).
+!> @param[out] THETA potential temperatures (K).
+!-----------------------------------------------------------------------
       SUBROUTINE CALPOT(P1D,T1D,THETA)
 
 !     

sorc/ncep_post.fd/CALRCH.f

@@ -21,6 +21,13 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>
 !> @author Russ Treadon W/NP2 @date 1993-10-11
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes GRD RCH number.
+!> 
+!> @param[in] EL Mixing length scale.
+!> @param[out] RICHNO Gradient Richardson number. 
+!-----------------------------------------------------------------------
+
       SUBROUTINE CALRCH(EL,RICHNO)
 
 !

sorc/ncep_post.fd/CALSTRM.f

@@ -22,6 +22,12 @@
 !> 2021-09-02 | Bo Cui          | Decompose UPP in X direction          
 !>
 !> @author Russ Treadon W/NP2 @date 1992-12-22
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes geo streamfunction.
+!>
+!> @param[in] Z1D Geopotential height (m).
+!> @param[out] STRM Geostrophic streamfunction.
+!-----------------------------------------------------------------------
       SUBROUTINE CALSTRM(Z1D,STRM)
 
 !     

sorc/ncep_post.fd/CALTAU.f

@@ -24,7 +24,12 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>
 !> @author Russ Treadon W/NP2 @date 1993-09-01
-
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes U and V wind stresses.
+!>
+!> @param[out] TAUX Suface layer U component wind stress.
+!> @param[out] TAUY Suface layer V component wind stress.
+!-----------------------------------------------------------------------
       SUBROUTINE CALTAU(TAUX,TAUY)
 
 !     

sorc/ncep_post.fd/CALTHTE.f

@@ -20,7 +20,14 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>     
 !> @author Russ Treadon W/NP2 @date 1993-06-18
-
+!--------------------------------------------------------------------------------------
+!> @brief Subroutine that computes Theta-E.
+!> 
+!> @param[in] P1D pressure (Pa).
+!> @param[in] T1D temperature (K).
+!> @param[in] Q1D specific humidity(kg/kg).
+!> @param[out] THTE Theta-E (K).
+!--------------------------------------------------------------------------------------
       SUBROUTINE CALTHTE(P1D,T1D,Q1D,THTE)
 
 !

sorc/ncep_post.fd/CALUPDHEL.f

@@ -15,6 +15,11 @@
 !> 2022-05-12 | E James  | Adding a check for extremely large positive or negative UH values
 !>     
 !> @author M Pyle W/NP2 @date 2007-10-22
+!--------------------------------------------------------------------------------------
+!> @brief Subroutine that computes the updraft helicity.
+!> 
+!> @param[out] UPDHEL Updraft helicity (m^2/s^2).
+!--------------------------------------------------------------------------------------
       SUBROUTINE CALUPDHEL(UPDHEL)
 
 !     

sorc/ncep_post.fd/CALWXT_BOURG.f

@@ -1,5 +1,5 @@
 !> @file
-!> @brief Subroutine that calculate precipitation type (Bourgouin).
+!> @brief Subroutine that calculates precipitation type (Bourgouin).
 !>
 !> This routine computes precipitation type.
 !> using a decision tree approach that uses the so-called
@@ -35,6 +35,7 @@
 !>                         ptype=4 freezing rain/mix with freezing rain
 !>                         ptype=8 rain
 !></pre>
+!> @param[in] me integer Identifier for the processor used in the current instance. 
 !>
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -50,8 +51,36 @@
 !>          and layer lmh = bottom
 !>
 !> @author M Baldwin np22 @date 1999-07-06
-
-      subroutine calwxt_bourg_post(im,ista_2l,iend_2u,ista,iend,jm,jsta_2l,jend_2u,jsta,jend,lm,lp1,   &
+!--------------------------------------------------------------------------------------
+!> @brief calwxt_bourg_post Subroutine that calculates precipitation type (Bourgouin).
+!> 
+!> @param[in] im integer i dimension.
+!> @param[in] ista_2l integer i dimension start point (including haloes).
+!> @param[in] iend_2u integer i dimension end point (including haloes).
+!> @param[in] ista integer i dimension start point (excluding haloes).
+!> @param[in] iend integer i dimension end point (excluding haloes).
+!> @param[in] jm integer j dimension.
+!> @param[in] jsta_2l integer j dimension start point (including haloes).
+!> @param[in] jend_2u integer j dimension end point (including haloes).
+!> @param[in] jsta integer j dimension start point (excluding haloes).
+!> @param[in] jend integer j dimension end point (excluding haloes).
+!> @param[in] lm integer k dimension.
+!> @param[in] lp1 integer k dimension plus 1.
+!> @param[in] iseed integer random number seed.
+!> @param[in] g real gravity (m/s**2).
+!> @param[in] pthresh real precipitation threshold (m).
+!> @param[in] t real(im,jsta_2l:jend_2u,lm) mid layer temp (K).
+!> @param[in] q real(im,jsta_2l:jend_2u,lm) specific humidity (kg/kg).
+!> @param[in] pmid real(im,jsta_2l:jend_2u,lm) mid layer pressure (Pa).
+!> @param[in] pint real(im,jsta_2l:jend_2u,lp1) interface pressure (Pa).
+!> @param[in] lmh real(im,jsta_2l:jend_2u) max number of layers.
+!> @param[in] prec real(im,jsta_2l:jend_2u) precipitation (m).
+!> @param[in] zint real(im,jsta_2l:jend_2u,lp1) interface height (m).
+!> @param[out] ptype integer(im,jm) instantaneous weather type () acts like a 4 bit binary 1111 = rain/freezing rain/ice pellets/snow.
+!> @param[in] me integer Identifier for the processor used in the current instance. 
+!------------------------------------------------------------------------------------------------------------
+      subroutine calwxt_bourg_post(im,ista_2l,iend_2u,ista,iend,jm,     &
+     &                              jsta_2l,jend_2u,jsta,jend,lm,lp1,   &
      &                             iseed,g,pthresh,                          &
      &                             t,q,pmid,pint,lmh,prec,zint,ptype,me)
       implicit none