From d1d06d67c5051858e2bdc5695d5d1f2f67c93e28 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 10 Mar 2021 22:21:11 +0000
Subject: [PATCH 01/22] doxygen updates to orog.fd.

Part of #191.
Fixes #408.
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f |  5 ++++
 sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90 | 23 ++++++++++++++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 85172dfd7..c96193419 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -4472,6 +4472,11 @@ subroutine nanc(a,l,c)
  102  format(' time to check ',i9,' words is ',f10.4,' ',a24)
       return
        end
+
+!> Get the date/time for the system clock.
+!!
+!! @author Mark Iredell
+!! @return timef
       real function timef()
       character(8) :: date
       character(10) :: time
diff --git a/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90 b/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
index f3c188434..685bb0064 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
+++ b/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
@@ -1,6 +1,23 @@
 !> @file
 !! @brief Write out data in netcdf format
+!! @author Jordan Alpert NOAA/EMC
+
+!> Write out orography file in netcdf format.
 !!
+!! @param[in] im ???
+!! @param[in] jm ???
+!! @param[in] slm ???
+!! @param[in] land_frac ???
+!! @param[in] oro ???
+!! @param[in] orf ???
+!! @param[in] hprime ???
+!! @param[in] ntiles ???
+!! @param[in] tile ???
+!! @param[in] geolon ???
+!! @param[in] geolat ??? 
+!! @param[in] lon ???
+!! @param[in] lat ???
+!! @author Jordan Alpert NOAA/EMC
   subroutine write_netcdf(im, jm, slm, land_frac, oro, orf, hprime, ntiles, tile, geolon, geolat, lon, lat)
     implicit none
     integer, intent(in):: im, jm, ntiles, tile
@@ -193,7 +210,11 @@ subroutine write_netcdf(im, jm, slm, land_frac, oro, orf, hprime, ntiles, tile,
       
   end subroutine
 
-!-------------------------------------------------------------------------------
+!> Check NetCDF error code and output the error message.
+!!
+!! @param[in] err NetCDF error code
+!! @param[in] string The NetCDF error message
+!! @author Jordan Alpert NOAA/EMC
   subroutine netcdf_err( err, string )
       integer, intent(in) :: err
       character(len=*), intent(in) :: string

From ec8801015a71dcb28854e158eac75d0d14bdfa4c Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Thu, 11 Mar 2021 20:21:59 +0000
Subject: [PATCH 02/22] Clear some doxygen warnings from orog.fd

Part of #191
Part of #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 117 ++++++++++--------
 sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90 |  28 ++---
 2 files changed, 82 insertions(+), 63 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index c96193419..09edea640 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -175,7 +175,6 @@
 !! @param EFAC
 !! @param BLAT 
 !! @param OUTGRID
-!! @param IFAC
 !! @param EFAC
 !! @param BLAT
 !! @param OUTGRID
@@ -3708,15 +3707,21 @@ SUBROUTINE MAKEOA3(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       RETURN
       END
       
+!> Reverse the east-west and north-south axes
+!! in a two-dimensional array.
+!!
+!! @param [in] im 'i' dimension of the 2-d array.
+!! @param [in] jm 'j' dimension of the 2-d array.
+!! @param [in] numi Not used.
+!! @param [inout] f The two-dimensional array to
+!! be processed.
+!! @param [out] wrk Two-dimensional work array.
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE REVERS(IM, JM, numi, F, WRK)
 !
       REAL F(IM,JM), WRK(IM,JM)
       integer numi(jm)
-C
-C     reverse east-west and north-south
-c......  fix this routine up to take numi (*j*)
-C.....   at least have 5 variables ....and keep REVLAT .FALSE.
-       imb2 = im / 2
+      imb2 = im / 2
       do i=1,im*jm
          WRK(i,1) = F(i,1)
       enddo
@@ -3775,10 +3780,16 @@ subroutine gg2rg(im,jm,numi,a)
           enddo
         enddo
       end subroutine
-      SUBROUTINE minmxj(IM,JM,A,title)
-
-c this routine is using real*4 on the sp
 
+!> Print out the maximum and minimum values of
+!! an array.
+!!
+!! @param[in] im The 'i' dimension of the array.
+!! @param[in] jm The 'i' dimension of the array.
+!! @param[in] a The array to check.
+!! @param[in] title Name of the data to be checked.
+!! @author Jordan Alpert NOAA/EMC
+      SUBROUTINE minmxj(IM,JM,A,title)
       implicit none
 
       real A(IM,JM),rmin,rmax
@@ -3801,10 +3812,19 @@ SUBROUTINE minmxj(IM,JM,A,title)
 C
       RETURN
       END
-      SUBROUTINE mnmxja(IM,JM,A,imax,jmax,title)
-
-c this routine is using real*4 on the sp
 
+!> Print out the maximum and minimum values of
+!! an array. Pass back the i/j location of the
+!! maximum value.
+!!
+!! @param[in] im The 'i' dimension of the array.
+!! @param[in] jm The 'i' dimension of the array.
+!! @param[in] a The array to check.
+!! @param[out] imax 'i' location of maximum
+!! @param[out] jmax 'j' location of maximum
+!! @param[in] title Name of the data to be checked.
+!! @author Jordan Alpert NOAA/EMC
+      SUBROUTINE mnmxja(IM,JM,A,imax,jmax,title)
       implicit none
 
       real A(IM,JM),rmin,rmax
@@ -3929,16 +3949,13 @@ SUBROUTINE SPFFT1(IMAX,INCW,INCG,KMAX,W,G,IDIR)
           END SELECT
         END SELECT
       END SUBROUTINE
+
+!> Read input global 30-arc second orography data.
+!!
+!! @param[out] glob The orography data.
+!! @param[in] itopo Not used.
+!! @author Jordan Alpert NOAA/EMC
       subroutine read_g(glob,ITOPO)
-!
-! --- if ITOPO = 1 then read gtopo30_gg.fine 43200X21600 30" file
-! --- if ITOPO = 2 then read  topo 30" .DEM tile files 
-! --- in either case, glob will be n Interger*2 array.
-! --- This routine write out a grads ctl file for displaying the 
-! --- tiles in the output working dir.  The glob array can not be 
-! --- acted on with grads, but the tiles can be if lat/lon are reduced slightly
-cc
-      use machine
       implicit none
 cc
       integer*2    glob(360*120,180*120)
@@ -3951,12 +3968,6 @@ subroutine read_g(glob,ITOPO)
 cc
       integer*2    idat(ix,jx)
       integer      itopo
-cc
-ccmr  integer*2    m9999 
-ccmr  data         m9999    / -9999 /
-cc
-ccmr  integer      i_count(360*120)
-ccmr  integer      j_max_y(360*120)
 cc
       integer      i,j,inttyp
 cc
@@ -3965,7 +3976,6 @@ subroutine read_g(glob,ITOPO)
       open(235, file="./fort.235", access='direct', recl=43200*21600*2)
       read(235,rec=1)glob
       close(235)
-cc
 cc
       print*,' '
       call maxmin     (glob,360*120*180*120,'global0')
@@ -3988,6 +3998,13 @@ subroutine read_g(glob,ITOPO)
 cc
       return
       end
+!> Print the maximum, mininum, mean and
+!! standard deviation of an array.
+!! 
+!! @param [in] ia The array to be checked.
+!! @param [in] len The number of points to be checked.
+!! @param [in] tile A name associated with the array.
+!! @author Jordan Alpert NOAA/EMC
       subroutine maxmin(ia,len,tile)
 ccmr
       implicit none
@@ -4036,10 +4053,17 @@ subroutine maxmin(ia,len,tile)
      &       ' ko9s=',kount,kount_9,kount+kount_9 
       return
       end
-      SUBROUTINE minmaxj(IM,JM,A,title)
-
-c this routine is using real*4 on the sp
 
+!> Print out the maximum and minimum values of
+!! an array and their i/j location. Also print out
+!! the number of undefined points.
+!!
+!! @param[in] im The 'i' dimension of the array.
+!! @param[in] jm The 'i' dimension of the array.
+!! @param[in] a The array to check.
+!! @param[in] title Name of the data to be checked.
+!! @author Jordan Alpert NOAA/EMC
+      SUBROUTINE minmaxj(IM,JM,A,title)
       implicit none
 
       real(kind=4) A(IM,JM),rmin,rmax,undef
@@ -4081,7 +4105,6 @@ SUBROUTINE minmaxj(IM,JM,A,title)
 C
       RETURN
       END
-
       
       !routine to map (lon, lat) to (x,y,z)
       subroutine latlon2xyz(siz,lon, lat, x, y, z)
@@ -4411,24 +4434,20 @@ subroutine get_xnsum3(lon1,lat1,lon2,lat2,IMN,JMN,
          
       end subroutine get_xnsum3
       
+!> Report NaNS and NaNQ within an address range for
+!! 8-byte real words.
+!!
+!! This routine prints a single line for each call
+!! and prints a message and returns to the caller on 
+!! detection of the FIRST NaN in the range.  If no NaN values
+!! are found it returns silently.
+!!
+!! @param[in] A Real*8 variable or array
+!! @param[in] L Number of words to scan (length of array)
+!! @param[in] C Distinctive message set in caller to indicate where
+!! the routine was called.
+!! @author Jordan Alpert NOAA/EMC
       subroutine nanc(a,l,c)
-c compiler opt TRAPS= -qinitauto=FF911299 -qflttrap=ov:zero:inv:en -qsig trap
-c or call subroutine below
-c subroutine to report NaNS and NaNQ within an address
-c range for real*8 words.
-c  as written the routine prints a single line for each call
-c  and prints a message and returns to the caller  on detection of the FIRST
-c  NaN in the range.  The message is passed in the  third
-c  argument.  If no NaN values are found it returns silently.
-c  A real*4 version can be created by making A real*4
-
-c    arguments (all are input only)
-c
-c    A   real*8 variable or array
-c    L   number of words to scan (length of array)
-c    C   distinctive message set in caller to indicate where
-c        the routine was called.
-c 
       integer inan1,inan2,inan3,inan4,inaq1,inaq2,inaq3,inaq4
        real word
        integer itest
diff --git a/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90 b/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
index 685bb0064..9e8875220 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
+++ b/sorc/orog_mask_tools.fd/orog.fd/netcdf_io.F90
@@ -4,20 +4,20 @@
 
 !> Write out orography file in netcdf format.
 !!
-!! @param[in] im ???
-!! @param[in] jm ???
-!! @param[in] slm ???
-!! @param[in] land_frac ???
-!! @param[in] oro ???
-!! @param[in] orf ???
-!! @param[in] hprime ???
-!! @param[in] ntiles ???
-!! @param[in] tile ???
-!! @param[in] geolon ???
-!! @param[in] geolat ??? 
-!! @param[in] lon ???
-!! @param[in] lat ???
-!! @author Jordan Alpert NOAA/EMC
+!! @param[in] im 'i' dimension of a model grid tile.
+!! @param[in] jm 'j' dimension of a model grid tile.
+!! @param[in] slm Land-sea mask.
+!! @param[in] land_frac Land fraction.
+!! @param[in] oro Orography
+!! @param[in] orf Filtered orography. Currently the same as 'oro'.
+!! @param[in] hprime The gravity wave drag fields on the model grid tile.
+!! @param[in] ntiles Number of tiles to output.
+!! @param[in] tile Tile number to output.
+!! @param[in] geolon Longitude on the model grid tile.
+!! @param[in] geolat Latitude on the model grid tile.
+!! @param[in] lon Longitude of the first row of the model grid tile.
+!! @param[in] lat Latitude of the first column of the model grid tile.
+!! @author Jordan Alpert NOAA/EMC GFDL Programmer
   subroutine write_netcdf(im, jm, slm, land_frac, oro, orf, hprime, ntiles, tile, geolon, geolat, lon, lat)
     implicit none
     integer, intent(in):: im, jm, ntiles, tile

From 5bdc3996254e7c11ffe1b2b1259457acd40e6f13 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Thu, 11 Mar 2021 21:25:26 +0000
Subject: [PATCH 03/22] Add doxygen to ./orog.fd/mtnlm7_oclsm.f.  Remove unused
 routine gl2any.

Part of #191
Fixes #408
Fixes #409
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 151 ++++--------------
 1 file changed, 34 insertions(+), 117 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 09edea640..cb48ff455 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -3157,70 +3157,6 @@ SUBROUTINE MAKEOA2(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       RETURN
       END
 
-
-C-----------------------------------------------------------------------
-      SUBROUTINE GL2ANY(IP,KM,G1,IM1,JM1,G2,IM2,JM2,IDRTI,RLON,RLAT)
-C$$$  SUBPROGRAM DOCUMENTATION BLOCK
-C
-C SUBPROGRAM:    GL2GL       INTERPOLATE GAUSSIAN GRID TO GAUSSIAN GRID
-C   PRGMMR: IREDELL          ORG: W/NMC23     DATE: 92-10-31
-C
-C ABSTRACT: LINEARLY INTERPOLATES GAUSSIAN GRID TO GAUSSIAN GRID.
-C
-C PROGRAM HISTORY LOG:
-C   91-10-31  MARK IREDELL
-C
-C USAGE:    CALL GL2GL(IP,KM,G1,IM1,JM1,G2,IM2,JM2)
-C   INPUT ARGUMENT LIST:
-C     IP           INTEGER INTERPOLATION TYPE
-C     KM           INTEGER NUMBER OF LEVELS
-C     G1           REAL (IM1,JM1,KM) INPUT GAUSSIAN FIELD
-C     IM1          INTEGER NUMBER OF INPUT LONGITUDES
-C     JM1          INTEGER NUMBER OF INPUT LATITUDES
-C     IM2          INTEGER NUMBER OF OUTPUT LONGITUDES
-C     JM2          INTEGER NUMBER OF OUTPUT LATITUDES
-C   OUTPUT ARGUMENT LIST:
-C     G2           REAL (IM2,JM2,KM) OUTPUT GAUSSIAN FIELD
-C
-C SUBPROGRAMS CALLED:
-C   IPOLATES     IREDELL'S POLATE FOR SCALAR FIELDS
-C
-C ATTRIBUTES:
-C   LANGUAGE: FORTRAN
-C
-CC$$$
-      REAL G1(IM1,JM1,KM),G2(IM2,JM2,KM)
-      LOGICAL*1 L1(IM1,JM1,KM),L2(IM2,JM2,KM)
-      REAL, intent(in) :: RLAT(IM2,JM2),RLON(IM2,JM2)
-      INTEGER IB1(KM),IB2(KM)
-      INTEGER KGDS1(200),KGDS2(200)
-      INTEGER IDRTI, IDRTO
-      DATA KGDS1/4,0,0,90000,0,0,-90000,193*0/
-      DATA KGDS2/4,0,0,90000,0,0,-90000,193*0/
-      INTEGER IPOPT(20)
-      DATA IPOPT/20*0/
-C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-      KGDS1(1) = IDRTI
-      KGDS2(1) = -1
-      NO = IM2*JM2
-      IF(IM1.NE.IM2.OR.JM1.NE.JM2) THEN
-        IB1=0
-        KGDS1(2)=IM1
-        KGDS1(3)=JM1
-        KGDS1(8)=NINT(-360000./IM1)
-        KGDS1(10)=JM1/2
-        KGDS2(2)=IM2
-        KGDS2(3)=JM2
-        KGDS2(8)=NINT(-360000./IM2)
-        KGDS2(10)=JM2/2
-        CALL IPOLATES(IP,IPOPT,KGDS1,KGDS2,IM1*JM1,IM2*JM2,KM,IB1,L1,G1,
-     &                NO,RLAT,RLON,IB2,L2,G2,IRET)
-      ELSE
-        G2=G1
-      ENDIF
-      END
-
-
       function spherical_distance(theta1,phi1,theta2,phi2)
 
       real, intent(in) :: theta1, phi1, theta2, phi2
@@ -3852,60 +3788,41 @@ SUBROUTINE mnmxja(IM,JM,A,imax,jmax,title)
       RETURN
       END
 
-C-----------------------------------------------------------------------
+!> Perform multiple fast fourier transforms.
+!!
+!! This subprogram performs multiple fast fourier transforms
+!! between complex amplitudes in fourier space and real values
+!! in cyclic physical space.
+!!
+!! Subprograms called (NCEPLIB SP Library):
+!!  - scrft Complex to real fourier transform
+!!  - dcrft Complex to real fourier transform
+!!  - srcft Real to complex fourier transform
+!!  - drcft Real to complex fourier transform
+!!
+!! Program history log:
+!! 1998-12-18  Mark Iredell
+!!
+!! @param[in] imax Integer number of values in the cyclic physical
+!! space. See limitations on imax in remarks below.
+!! @param[in] incw Integer first dimension of the complex amplitude array.
+!! (incw >= imax/2+1).
+!! @param[in] incg Integer first dimension of the real value array.
+!! (incg >= imax).
+!! @param[in] kmax Integer number of transforms to perform.
+!! @param[in] w Complex amplitudes on input if idir>0, and on output
+!! if idir<0.
+!! @param[in] g Real values on input if idir<0, and on output if idir>0.
+!! @param[in] idir Integer direction flag. idir>0 to transform from
+!! fourier to physical space. idir<0 to transform from physical to
+!! fourier space.
+!!
+!! @note The restrictions on imax are that it must be a multiple
+!! of 1 to 25 factors of two, up to 2 factors of three,
+!! and up to 1 factor of five, seven and eleven.
+!!
+!! @author Mark Iredell ORG: W/NMC23 @date 96-02-20
       SUBROUTINE SPFFT1(IMAX,INCW,INCG,KMAX,W,G,IDIR)
-C$$$  SUBPROGRAM DOCUMENTATION BLOCK
-C
-C SUBPROGRAM:  SPFFT1     PERFORM MULTIPLE FAST FOURIER TRANSFORMS
-C   PRGMMR: IREDELL       ORG: W/NMC23       DATE: 96-02-20
-C
-C ABSTRACT: THIS SUBPROGRAM PERFORMS MULTIPLE FAST FOURIER TRANSFORMS
-C           BETWEEN COMPLEX AMPLITUDES IN FOURIER SPACE AND REAL VALUES
-C           IN CYCLIC PHYSICAL SPACE.
-C           SUBPROGRAM SPFFT1 INITIALIZES TRIGONOMETRIC DATA EACH CALL.
-C           USE SUBPROGRAM SPFFT TO SAVE TIME AND INITIALIZE ONCE.
-C           THIS VERSION INVOKES THE IBM ESSL FFT.
-C
-C PROGRAM HISTORY LOG:
-C 1998-12-18  IREDELL
-C
-C USAGE:    CALL SPFFT1(IMAX,INCW,INCG,KMAX,W,G,IDIR)
-C
-C   INPUT ARGUMENT LIST:
-C     IMAX     - INTEGER NUMBER OF VALUES IN THE CYCLIC PHYSICAL SPACE
-C                (SEE LIMITATIONS ON IMAX IN REMARKS BELOW.)
-C     INCW     - INTEGER FIRST DIMENSION OF THE COMPLEX AMPLITUDE ARRAY
-C                (INCW >= IMAX/2+1)
-C     INCG     - INTEGER FIRST DIMENSION OF THE REAL VALUE ARRAY
-C                (INCG >= IMAX)
-C     KMAX     - INTEGER NUMBER OF TRANSFORMS TO PERFORM
-C     W        - COMPLEX(INCW,KMAX) COMPLEX AMPLITUDES IF IDIR>0
-C     G        - REAL(INCG,KMAX) REAL VALUES IF IDIR<0
-C     IDIR     - INTEGER DIRECTION FLAG
-C                IDIR>0 TO TRANSFORM FROM FOURIER TO PHYSICAL SPACE
-C                IDIR<0 TO TRANSFORM FROM PHYSICAL TO FOURIER SPACE
-C
-C   OUTPUT ARGUMENT LIST:
-C     W        - COMPLEX(INCW,KMAX) COMPLEX AMPLITUDES IF IDIR<0
-C     G        - REAL(INCG,KMAX) REAL VALUES IF IDIR>0
-C
-C SUBPROGRAMS CALLED:
-C   SCRFT        IBM ESSL COMPLEX TO REAL FOURIER TRANSFORM
-C   DCRFT        IBM ESSL COMPLEX TO REAL FOURIER TRANSFORM
-C   SRCFT        IBM ESSL REAL TO COMPLEX FOURIER TRANSFORM
-C   DRCFT        IBM ESSL REAL TO COMPLEX FOURIER TRANSFORM
-C
-C ATTRIBUTES:
-C   LANGUAGE: FORTRAN 90
-C
-C REMARKS:
-C   THE RESTRICTIONS ON IMAX ARE THAT IT MUST BE A MULTIPLE
-C   OF 1 TO 25 FACTORS OF TWO, UP TO 2 FACTORS OF THREE,
-C   AND UP TO 1 FACTOR OF FIVE, SEVEN AND ELEVEN.
-C
-C   THIS SUBPROGRAM IS THREAD-SAFE.
-C
-C$$$
         IMPLICIT NONE
         INTEGER,INTENT(IN):: IMAX,INCW,INCG,KMAX,IDIR
         COMPLEX,INTENT(INOUT):: W(INCW,KMAX)

From cb271d446a19c47562abcdf6a3a915be141aba6f Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Thu, 11 Mar 2021 22:19:26 +0000
Subject: [PATCH 04/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191.
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index cb48ff455..e567f545a 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -160,27 +160,27 @@
      &            OUTGRID,INPUTOROG)
       STOP
       END
-!>
-!!  @note  Subroutine TERSUB is undocumented by developer 
-!!         Inserting doxygen framework only including undescribed params
-!! @param IMN
-!! @param JMN 
-!! @param IM
-!! @param JM 
-!! @param NM 
-!! @param NR 
-!! @param NF0
-!! @param NF1
-!! @param NW 
-!! @param EFAC
-!! @param BLAT 
-!! @param OUTGRID
-!! @param EFAC
-!! @param BLAT
-!! @param OUTGRID
-!! @param INPUTOROG
+
+!> Driver routine to compute terrain.
 !!
-!! @author Mark Iredell
+!! @param[in] IMN "i" dimension of the input terrain dataset.
+!! @param[in] JMN "j" dimension of the input terrain dataset.
+!! @param[in] IM "i" dimension of the model grid tile.
+!! @param[in] JM "j" dimension of the model grid tile.
+!! @param[in] NM Spectral truncation.
+!! @param[in] NR Rhomboidal flag.
+!! @param[in] NF0 First order spectral filter parameters.
+!! @param[in] NF1 Second order spectral filter parameters.
+!! @param[in] NW ???
+!! @param[in] EFAC ???
+!! @param[in] BLAT When less than zero, reverse latitude/
+!! longitude for output.
+!! @param[in] OUTGRID The 'grid' file for the model tile.
+!! @param[in] INPUTOROG Input orography/GWD file on gaussian
+!! grid. When specified, will be interpolated to model tile.
+!! When not specified, program will create fields from
+!! raw high-resolution topography data.
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
      &     OUTGRID,INPUTOROG)
 !jaa      use ipfort

From 3e4c291ab5c9c9bc6cc00ebc18e5036d80911727 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Fri, 12 Mar 2021 20:44:11 +0000
Subject: [PATCH 05/22] Clear some doxygen warnings from orog.fd

Part of #191
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 202 +++++++++++++++++-
 1 file changed, 195 insertions(+), 7 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index e567f545a..389420182 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -2196,6 +2196,21 @@ SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
       RETURN
       END
 
+!> makepc2
+!!
+!! @param[in] zavg ???
+!! @param[in] zslm ???
+!! @param[in] theta ???
+!! @param[in] gamma ???
+!! @param[in] sigma ???
+!! @param[in] glat ???
+!! @param[in] im ???
+!! @param[in] jm ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] lon_c ???
+!! @param[in] lat_c ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
 C
@@ -2429,6 +2444,33 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
       RETURN
       END
       
+!> makeoa
+!!
+!! @param[in] zavg ???
+!! @param[in] var ???
+!! @param[in] glat ???
+!! @param[in] oa4 ???
+!! @param[in] ol ???
+!! @param[in] ioa4 ???
+!! @param[in] elvmax ???
+!! @param[in] oro ???
+!! @param[in] oro1 ???
+!! @param[in] xnsum ???
+!! @param[in] xnsum1 ???
+!! @param[in] xnsum2 ???
+!! @param[in] xnsum3 ???
+!! @param[in] xnsum4 ???
+!! @param[in] ist ???
+!! @param[in] ien ???
+!! @param[in] jst ???
+!! @param[in] jen ???
+!! @param[in] im  ???
+!! @param[in] jm ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] xlat ???
+!! @param[in] numi ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEOA(ZAVG,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
      2           IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
@@ -2748,7 +2790,13 @@ SUBROUTINE MAKEOA(ZAVG,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       RETURN
       END
 
-
+!> Get longitude angle
+!!
+!! @param[in] dx ???
+!! @param[in] lat ???
+!! @param[in] degrad ???
+!! @return get_lon_angle Longitude angle.
+!! @author GFDL programmer
       function get_lon_angle(dx,lat, DEGRAD)
       implicit none
       real dx, lat, DEGRAD
@@ -2760,6 +2808,12 @@ function get_lon_angle(dx,lat, DEGRAD)
          
       end function get_lon_angle
 
+!> Get latitude angle
+!!
+!! @param[in] dy ???
+!! @param[in] degrad ???
+!! @return get_lat_angle ???
+!! @author GFDL programmer
       function get_lat_angle(dy, DEGRAD)
       implicit none
       real dy, DEGRAD
@@ -3156,7 +3210,15 @@ SUBROUTINE MAKEOA2(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
 C
       RETURN
       END
-
+ 
+!> Compute a great circle distance
+!!
+!! @param[in] theta1 ???
+!! @param[in] phi1 ???
+!! @param[in] theta2 ???
+!! @param[in] phi2 ???
+!! @return spherical_distance Great circle distance.
+!! @author GFDL programmer
       function spherical_distance(theta1,phi1,theta2,phi2)
 
       real, intent(in) :: theta1, phi1, theta2, phi2
@@ -3176,6 +3238,19 @@ function spherical_distance(theta1,phi1,theta2,phi2)
 
       end function spherical_distance
       
+!> Get mismatch index
+!!
+!! @param[in] im_in ???
+!! @param[in] jm_in ???
+!! @param[in] geolon_in ???
+!! @param[in] geolat_in ???
+!! @param[in] bitmap_in ???
+!! @param[in] num_out ???
+!! @param[in] lon_out ???
+!! @param[in] lat_out ???
+!! @param[out] iindx ???
+!! @param[out] jindx ???
+!! @author GFDL progammer
       subroutine get_mismatch_index(im_in, jm_in, geolon_in,geolat_in,
      &           bitmap_in,num_out, lon_out,lat_out, iindx, jindx )
       integer, intent(in) :: im_in, jm_in, num_out
@@ -3244,7 +3319,16 @@ subroutine get_mismatch_index(im_in, jm_in, geolon_in,geolat_in,
 
       end subroutine get_mismatch_index
       
-
+!> Interpolate mismatch
+!!
+!! @param[in] im_in ???
+!! @param[in] jm_in ???
+!! @param[in] data_in ???
+!! @param[in] num_out ???
+!! @param[out] data_out ???
+!! @param[in] iindx ???
+!! @param[in] jindx ???
+!! @author GFDL programmer
       subroutine interpolate_mismatch(im_in, jm_in, data_in,
      &                                num_out, data_out, iindx, jindx)
       integer, intent(in) :: im_in, jm_in, num_out
@@ -3258,6 +3342,42 @@ subroutine interpolate_mismatch(im_in, jm_in, data_in,
 
       end subroutine interpolate_mismatch
       
+!> Makeoa3
+!!
+!! @param[in] zavg ???
+!! @param[in] zslm ???
+!! @param[in] var ???
+!! @param[in] glat ???
+!! @param[in] oa4 ???
+!! @param[in] ol ???
+!! @param[in] ioa4 ???
+!! @param[in] elvmax ???
+!! @param[in] oro ???
+!! @param[in] slm ???
+!! @param[in] oro1 ???
+!! @param[in] xnsum ???
+!! @param[in] xnsum1 ???
+!! @param[in] xnsum2 ???
+!! @param[in] xnsum3 ???
+!! @param[in] xnsum4 ???
+!! @param[in] im ???
+!! @param[in] jm ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] lon_c ???
+!! @param[in] lat_c ???
+!! @param[in] lon_t ???
+!! @param[in] lat_t ???
+!! @param[in] is_south_pole ???
+!! @param[in] is_north_pole ???
+!! @param[in] imi ???
+!! @param[in] jmi ???
+!! @param[in] oa_in ???
+!! @param[in] ol_in ???
+!! @param[in] slm_in ???
+!! @param[in] lon_in ???
+!! @param[in] lat_in ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEOA3(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,SLM,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
      2           IM,JM,IMN,JMN,lon_c,lat_c,lon_t,lat_t,
@@ -3915,6 +4035,7 @@ subroutine read_g(glob,ITOPO)
 cc
       return
       end
+
 !> Print the maximum, mininum, mean and
 !! standard deviation of an array.
 !! 
@@ -4023,7 +4144,15 @@ SUBROUTINE minmaxj(IM,JM,A,title)
       RETURN
       END
       
-      !routine to map (lon, lat) to (x,y,z)
+!> Convert from latitude and longitude to x,y,z coordinates.
+!!
+!! @param[in] siz ???
+!! @param[in] lon ???
+!! @param[in] lat ???
+!! @param[out] x ???
+!! @param[out] y ???
+!! @param[out] z ???
+!! @author GFDL programmer
       subroutine latlon2xyz(siz,lon, lat, x, y, z)
       implicit none
       integer, intent(in) :: siz
@@ -4039,6 +4168,13 @@ subroutine latlon2xyz(siz,lon, lat, x, y, z)
       enddo
       end
 
+!> Compute spherical angle.
+!!
+!! @param[in] v1 ???
+!! @param[in] v2 ???
+!! @param[in] v3 ???
+!! @return spherical_angle Spherical Angle.
+!! @author GFDL programmer
       FUNCTION spherical_angle(v1, v2, v3)
         implicit none
         real, parameter :: EPSLN30 = 1.e-30
@@ -4079,6 +4215,15 @@ FUNCTION spherical_angle(v1, v2, v3)
         return
       END  
       
+!> Check to see if a point is inside a polygon.
+!!
+!! @param[in] lon1 ???
+!! @param[in] lat1 ???
+!! @param[in] npts ???
+!! @param[in] lon2 ???
+!! @param[in] lat2 ???
+!! @return inside_a_polygon ???
+!! @author GFDL programmer
       FUNCTION inside_a_polygon(lon1, lat1, npts, lon2, lat2)
         implicit none
         real, parameter :: EPSLN10 = 1.e-10
@@ -4151,7 +4296,20 @@ FUNCTION inside_a_polygon(lon1, lat1, npts, lon2, lat2)
         
       end
 
-
+!> Get xnsum
+!!
+!! @param[in] lon1  ???
+!! @param[in] lat1  ???
+!! @param[in] lon2  ???
+!! @param[in] lat2  ???
+!! @param[in] imn   ???
+!! @param[in] jmn   ??? 
+!! @param[in] glat  ???
+!! @param[in] zavg  ???
+!! @param[in] zslm  ???
+!! @param[in] delxn  ???
+!! @return get_xnsum ???
+!! @author Jordan Alpert NOAA/EMC
       function get_xnsum(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn)
         implicit none
@@ -4231,7 +4389,22 @@ function get_xnsum(lon1,lat1,lon2,lat2,IMN,JMN,
          
       end function get_xnsum  
       
-
+!> Get xnnum2
+!!
+!! @param[in] lon1  ???
+!! @param[in] lat1  ???
+!! @param[in] lon2  ???
+!! @param[in] lat2  ???
+!! @param[in] imn   ???
+!! @param[in] jmn   ??? 
+!! @param[in] glat  ???
+!! @param[in] zavg  ???
+!! @param[in] zslm  ???
+!! @param[in] delxn  ???
+!! @param[in] xnsum1 ???
+!! @param[in] xnsum2 ???
+!! @param[in] hc ???
+!! @author Jordan Alpert NOAA/EMC
       subroutine get_xnsum2(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)
         implicit none
@@ -4299,7 +4472,22 @@ subroutine get_xnsum2(lon1,lat1,lon2,lat2,IMN,JMN,
          
       end subroutine get_xnsum2 
 
-
+!> Get xnnum3
+!!
+!! @param[in] lon1  ???
+!! @param[in] lat1  ???
+!! @param[in] lon2  ???
+!! @param[in] lat2  ???
+!! @param[in] imn   ???
+!! @param[in] jmn   ??? 
+!! @param[in] glat  ???
+!! @param[in] zavg  ???
+!! @param[in] zslm  ???
+!! @param[in] delxn  ???
+!! @param[in] xnsum1 ???
+!! @param[in] xnsum2 ???
+!! @param[in] hc ???
+!! @author Jordan Alpert NOAA/EMC
       subroutine get_xnsum3(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)
         implicit none

From 96c4a407cd2f3db04073373815a7952537b5360f Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Fri, 12 Mar 2021 21:42:26 +0000
Subject: [PATCH 06/22] Clear more doxygen warnings from orog.fd

Part of #191
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 142 +++++++++++++++---
 1 file changed, 119 insertions(+), 23 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 389420182..b03e2b6bd 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -1,7 +1,7 @@
 C> @file
 C> TERRAIN MAKER FOR GLOBAL SPECTRAL MODEL
 C> @author IREDELL @date 92-04-16
-C>
+  
 C> THIS PROGRAM CREATES 7 TERRAIN-RELATED FILES
 C>   COMPUTED FROM THE NAVY 10-MINUTE TERRAIN DATASET.
 C>   THE MODEL PHYSICS GRID PARAMETERS AND SPECTRAL TRUNCATION
@@ -72,7 +72,8 @@
 C>  -   GBYTES     - UNPACK BITS
 C>
 C>   REMARKS: FORTRAN 9X EXTENSIONS ARE USED.
-C>           
+C>
+C> @return 0 for success, error code otherwise.
       include 'netcdf.inc'
       logical fexist, opened
       integer fsize, ncid, error, id_dim, nx, ny
@@ -1566,27 +1567,27 @@ SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
       write(6,*)' Total runtime time= ',tend-tbeg1
       RETURN
       END
-!>
-!! @note undocumented subroutine MAKEMT  
-!! @param ZAVG
-!! @param ZSLM
-!! @param ORO  
-!! @param SLM  
-!! @param VAR  
-!! @param VAR4 
-!! @param GLAT
-!! @param IST 
-!! @param IEN 
-!! @param JST 
-!! @param JEN 
-!! @param IM  
-!! @param JM  
-!! @param IMN 
-!! @param JMN 
-!! @param XLAT
-!! @param numi
+
+!> makemt
 !!
-!! @author unknown, probably Mark Iredell
+!! @param[in] zavg ???
+!! @param[in] zslm ???
+!! @param[in] oro  ???
+!! @param[in] slm  ???
+!! @param[in] var  ???
+!! @param[in] var4 ???
+!! @param[in] glat ???
+!! @param[in] ist ???
+!! @param[in] ien ???
+!! @param[in] jst ???
+!! @param[in] jen ???
+!! @param[in] im  ???
+!! @param[in] jm  ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] xlat ???
+!! @param[in] numi ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEMT(ZAVG,ZSLM,ORO,SLM,VAR,VAR4,
      1 GLAT,IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
       DIMENSION GLAT(JMN),XLAT(JM)
@@ -1734,6 +1735,19 @@ SUBROUTINE MAKEMT(ZAVG,ZSLM,ORO,SLM,VAR,VAR4,
       RETURN
       END
 
+!> Get index
+!!
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] npts ???
+!! @param[in] lonO ???
+!! @param[in] latO ???
+!! @param[in] delxn ???
+!! @param[out] jst ???
+!! @param[out] jen ???
+!! @param[out] ilist ???
+!! @param[out] numx ???
+!! @author GFDL programmer
       SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
      &           jst,jen,ilist,numx)
         implicit none
@@ -1808,6 +1822,23 @@ SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
 
       END   
       
+!> makemt2
+!!
+!! @param[in] zavg ???
+!! @param[in] zslm ???
+!! @param[in] oro ???
+!! @param[in] slm ???
+!! @param[in] land_frac ???
+!! @param[in] var ???
+!! @param[in] var4 ???
+!! @param[in] glat ???
+!! @param[in] im ???
+!! @param[in] jm ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] lon_c ???
+!! @param[in] lat_c ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
      1 GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
       implicit none
@@ -1940,7 +1971,25 @@ SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
       RETURN
       END
 
-      
+!> makepc
+!!
+!! @param[in] zavg ???
+!! @param[in] zslm ???
+!! @param[in] theta ???
+!! @param[in] gamma ???
+!! @param[in] sigma ???
+!! @param[in] glat ???
+!! @param[in] ist ???
+!! @param[in] ien ???
+!! @param[in] jst ???
+!! @param[in] jen ???
+!! @param[in] im ???
+!! @param[in] jm ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] xlat ???
+!! @param[in] numi ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
 C
@@ -2825,6 +2874,36 @@ function get_lat_angle(dy, DEGRAD)
          
       end function get_lat_angle
       
+!> makeoa2
+!!
+!! @param[in] zavg ???
+!! @param[in] zslm  ???
+!! @param[in] var ???
+!! @param[in] glat ???
+!! @param[in] oa4 ???
+!! @param[in] ol ???
+!! @param[in] ioa4 ???
+!! @param[in] elvmax ???
+!! @param[in] oro ???
+!! @param[in] oro1 ???
+!! @param[in] xnsum ???
+!! @param[in] xnsum1 ???
+!! @param[in] xnsum2 ???
+!! @param[in] xnsum3 ???
+!! @param[in] xnsum4, ???
+!! @param[in] im ???
+!! @param[in] jm  ???
+!! @param[in] imn ???
+!! @param[in] jmn ???
+!! @param[in] lon_c ???
+!! @param[in] lat_c ???
+!! @param[in] lon_t ???
+!! @param[in] lat_t ???
+!! @param[in] dx ???
+!! @param[in] dy ???
+!! @param[in] is_south_pole ???
+!! @param[in] is_north_pole ???
+!! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEOA2(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
      2           IM,JM,IMN,JMN,lon_c,lat_c,lon_t,lat_t,dx,dy,
@@ -3802,6 +3881,14 @@ SUBROUTINE REVERS(IM, JM, numi, F, WRK)
       RETURN
       END
 
+!> Convert from a reduced grid to a full grid.
+!!
+!! @param[in] im 'i' dimension of the full grid.
+!! @param[in] jm 'j' dimension of the full grid.
+!! @param[in] numi Number of 'i' points for each
+!! row of the reduced grid.
+!! @param[inout] a The data to be converted.
+!! @author Jordan Alpert NOAA/EMC
       subroutine rg2gg(im,jm,numi,a)
         implicit none
         integer,intent(in):: im,jm,numi(jm)
@@ -3819,6 +3906,15 @@ subroutine rg2gg(im,jm,numi,a)
           enddo
         enddo
       end subroutine
+
+!> Convert from a full grid to a reduced grid.
+!!
+!! @param[in] im 'i' dimension of the full grid.
+!! @param[in] jm 'j' dimension of the full grid.
+!! @param[in] numi Number of 'i' points for each
+!! row of the reduced grid.
+!! @param[inout] a The data to be converted.
+!! @author Jordan Alpert NOAA/EMC
       subroutine gg2rg(im,jm,numi,a)
         implicit none
         integer,intent(in):: im,jm,numi(jm)

From 4738d89022391686f721d9e5b2ecd80ed3715825 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Fri, 12 Mar 2021 21:58:36 +0000
Subject: [PATCH 07/22] Get rid of unused machine.f90 from orog.fd.

Part of #191
Part of #408
Fixes #413
---
 sorc/orog_mask_tools.fd/orog.fd/CMakeLists.txt |  1 -
 sorc/orog_mask_tools.fd/orog.fd/machine.f90    | 14 --------------
 sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f |  1 -
 3 files changed, 16 deletions(-)
 delete mode 100644 sorc/orog_mask_tools.fd/orog.fd/machine.f90

diff --git a/sorc/orog_mask_tools.fd/orog.fd/CMakeLists.txt b/sorc/orog_mask_tools.fd/orog.fd/CMakeLists.txt
index 9ed6f78cc..5e38c7a35 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/CMakeLists.txt
+++ b/sorc/orog_mask_tools.fd/orog.fd/CMakeLists.txt
@@ -1,5 +1,4 @@
 set(fortran_src
-    machine.f90
     mtnlm7_oclsm.f
     netcdf_io.F90)
 
diff --git a/sorc/orog_mask_tools.fd/orog.fd/machine.f90 b/sorc/orog_mask_tools.fd/orog.fd/machine.f90
deleted file mode 100644
index 134331577..000000000
--- a/sorc/orog_mask_tools.fd/orog.fd/machine.f90
+++ /dev/null
@@ -1,14 +0,0 @@
-!> @file
-!! @brief Machine dependant constants
- module machine
-!
- integer    kind_io2,kind_io4,kind_io8
- integer    kind_evod
-!
- parameter (kind_io2 =2)
- parameter (kind_io4 =4)
- parameter (kind_io8 =8)
- parameter (kind_evod=8)
- real(kind=kind_evod) mprec !< machine precision to restrict dep
- parameter(mprec  = 1.e-12 )
- end module machine
diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index b03e2b6bd..95bed2f15 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -185,7 +185,6 @@
       SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
      &     OUTGRID,INPUTOROG)
 !jaa      use ipfort
-      use machine
       implicit none
       include 'netcdf.inc'
 C

From 85221142b26c022c62992387a2fe83ac3e6346f0 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Fri, 12 Mar 2021 22:57:50 +0000
Subject: [PATCH 08/22] Clear doxygen warnings from lake.fd code.

Part of #191
Fixes #408
---
 .../orog_mask_tools.fd/lake.fd/find_limit.F90 | 10 ++++
 sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90  | 54 +++++++++++++++++--
 2 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90 b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
index cc035c671..9c871ce34 100644
--- a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
+++ b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
@@ -1,4 +1,14 @@
 !> @file
+!! @brief Find limit
+!! @author Ning Wang
+
+!> Find limit
+!!
+!! @param[in] p1_in ???
+!! @param[in] p2_in ???
+!! @param[out] latmin ???
+!! @param[out] latmax ???
+!! @author Ning Wang
 !#define DIAG
 SUBROUTINE find_limit (p1_in, p2_in, latmin, latmax)
     REAL*8, INTENT(IN) :: p1_in(2), p2_in(2)
diff --git a/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90 b/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
index 81b459eb6..a419f8c1f 100644
--- a/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
+++ b/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
@@ -1,5 +1,8 @@
 !> @file
-!! This program computes lake fraction and depth numbers for FV3 cubed sphere 
+!! @brief Compute lake fraction and depth.
+!! @author Ning Wang
+
+!> This program computes lake fraction and depth numbers for FV3 cubed sphere 
 !! grid cells, from a high resolution lat/lon data set.
 !! 
 !! @author Ning Wang @date July 2018
@@ -12,6 +15,7 @@
 !!  - Ning Wang, Apr. 2019: Extended the program to process the same lake data 
 !!                         for FV3 stand-alone regional (SAR) model.
 !!     
+!! @return 0 for successful completion and for error.
 !#define DIAG_N_VERBOSE
 #define ADD_ATT_FOR_NEW_VAR
 PROGRAM lake_frac
@@ -129,6 +133,13 @@ PROGRAM lake_frac
     STOP
 CONTAINS
 
+!> Calculate lake fraction depth
+!!
+!! @param[in] lakestat ???
+!! @param[in] lakedpth ???
+!! @param[out] cs_lakestat ???
+!! @param[out] cs_lakedpth ???
+!! @author Ning Wang
 SUBROUTINE cal_lake_frac_depth(lakestat,cs_lakestat,lakedpth,cs_lakedpth)
     INTEGER*1, INTENT(IN) :: lakestat(:)
     INTEGER*2, INTENT(IN) :: lakedpth(:)
@@ -358,7 +369,11 @@ SUBROUTINE cal_lake_frac_depth(lakestat,cs_lakestat,lakedpth,cs_lakedpth)
 
 END SUBROUTINE cal_lake_frac_depth 
 
- 
+!> Read cubed sphere grid
+!!
+!! @param[in] res ???
+!! @param[out] grid ???
+!! @author Ning Wang
 SUBROUTINE read_cubed_sphere_grid(res, grid) 
     INTEGER, INTENT(IN) :: res
     REAL, INTENT(OUT) :: grid(:,:)
@@ -411,6 +426,14 @@ SUBROUTINE read_cubed_sphere_grid(res, grid)
 
 END SUBROUTINE read_cubed_sphere_grid
 
+!> Read cubed sphere reg grid
+!!
+!! @param[in] res ???
+!! @param[out] grid ???
+!! @param[in] halo_depth ???
+!! @param[out] res_x ???
+!! @param[out] res_y ???
+!! @author Ning Wang
 SUBROUTINE read_cubed_sphere_reg_grid(res, grid, halo_depth, res_x, res_y) 
     INTEGER, INTENT(IN) :: res, halo_depth
     INTEGER, INTENT(OUT) :: res_x, res_y
@@ -471,6 +494,13 @@ SUBROUTINE read_cubed_sphere_reg_grid(res, grid, halo_depth, res_x, res_y)
 
 END SUBROUTINE read_cubed_sphere_reg_grid
 
+!> Read lake data
+!!
+!! @param[in] lakedata_path ???
+!! @param[out] lake_stat ???
+!! @param[out] lake_dpth ???
+!! @param[in] nlat ???
+!! @param[in] nlon ???
 SUBROUTINE read_lakedata(lakedata_path,lake_stat,lake_dpth,nlat,nlon)
     CHARACTER(len=256), INTENT(IN) :: lakedata_path
     INTEGER*1, INTENT(OUT) :: lake_stat(:)
@@ -495,7 +525,12 @@ SUBROUTINE read_lakedata(lakedata_path,lake_stat,lake_dpth,nlat,nlon)
 
 END SUBROUTINE read_lakedata
    
-
+!> Write lake data to oro data.
+!!
+!! @param[in] cs_res ???
+!! @param[in] cs_lakestat ???
+!! @param[in] cs_lakedpth ???
+!! @author Ning Wang
 SUBROUTINE write_lakedata_to_orodata(cs_res, cs_lakestat, cs_lakedpth) 
     USE netcdf 
     INTEGER, INTENT(IN) :: cs_res
@@ -685,6 +720,14 @@ SUBROUTINE write_lakedata_to_orodata(cs_res, cs_lakestat, cs_lakedpth)
   
 END SUBROUTINE write_lakedata_to_orodata
 
+!> write reg lake data to oro data.
+!!
+!! @param[in] cs_res ???
+!! @param[in] tile_x_dim ???
+!! @param[in] tile_y_dim ???
+!! @param[in] cs_lakestat ???
+!! @param[in] cs_lakedpth ???
+!! @author Ning Wang
 SUBROUTINE write_reg_lakedata_to_orodata(cs_res, tile_x_dim, tile_y_dim, cs_lakestat, cs_lakedpth) 
     USE netcdf 
     INTEGER, INTENT(IN) :: cs_res, tile_x_dim, tile_y_dim
@@ -887,6 +930,11 @@ SUBROUTINE write_reg_lakedata_to_orodata(cs_res, tile_x_dim, tile_y_dim, cs_lake
 
 END SUBROUTINE write_reg_lakedata_to_orodata
 
+!> Check NetCDF error code
+!!
+!! @param[in] stat Error code.
+!! @param[in] opname NetCDF operation that failed.
+!! @author Ning Wang
 SUBROUTINE nc_opchk(stat,opname)
    USE netcdf
    IMPLICIT NONE

From b74424f1c18243105d29ff1a5641f5ed8a865ae3 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Mon, 15 Mar 2021 18:39:45 +0000
Subject: [PATCH 09/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 95bed2f15..640105687 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -173,7 +173,7 @@
 !! @param[in] NF0 First order spectral filter parameters.
 !! @param[in] NF1 Second order spectral filter parameters.
 !! @param[in] NW ???
-!! @param[in] EFAC ???
+!! @param[in] EFAC Factor to adjust orography by its variance.
 !! @param[in] BLAT When less than zero, reverse latitude/
 !! longitude for output.
 !! @param[in] OUTGRID The 'grid' file for the model tile.
@@ -1580,8 +1580,8 @@ SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
 !! @param[in] ien ???
 !! @param[in] jst ???
 !! @param[in] jen ???
-!! @param[in] im  ???
-!! @param[in] jm  ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] xlat ???
@@ -1831,8 +1831,8 @@ SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
 !! @param[in] var ???
 !! @param[in] var4 ???
 !! @param[in] glat ???
-!! @param[in] im ???
-!! @param[in] jm ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] lon_c ???
@@ -1982,8 +1982,8 @@ SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
 !! @param[in] ien ???
 !! @param[in] jst ???
 !! @param[in] jen ???
-!! @param[in] im ???
-!! @param[in] jm ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] xlat ???
@@ -2252,8 +2252,8 @@ SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
 !! @param[in] gamma ???
 !! @param[in] sigma ???
 !! @param[in] glat ???
-!! @param[in] im ???
-!! @param[in] jm ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] lon_c ???
@@ -2496,7 +2496,7 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
 !!
 !! @param[in] zavg ???
 !! @param[in] var ???
-!! @param[in] glat ???
+!! @param[out] glat Latitude of each row of input terrain dataset.
 !! @param[in] oa4 ???
 !! @param[in] ol ???
 !! @param[in] ioa4 ???
@@ -2512,10 +2512,10 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
 !! @param[in] ien ???
 !! @param[in] jst ???
 !! @param[in] jen ???
-!! @param[in] im  ???
-!! @param[in] jm ???
-!! @param[in] imn ???
-!! @param[in] jmn ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
+!! @param[in] imn "i" dimension of the input terrain dataset.
+!! @param[in] jmn "j" dimension of the input terrain dataset.
 !! @param[in] xlat ???
 !! @param[in] numi ???
 !! @author Jordan Alpert NOAA/EMC
@@ -2890,8 +2890,8 @@ end function get_lat_angle
 !! @param[in] xnsum2 ???
 !! @param[in] xnsum3 ???
 !! @param[in] xnsum4, ???
-!! @param[in] im ???
-!! @param[in] jm  ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] lon_c ???
@@ -3438,8 +3438,8 @@ end subroutine interpolate_mismatch
 !! @param[in] xnsum2 ???
 !! @param[in] xnsum3 ???
 !! @param[in] xnsum4 ???
-!! @param[in] im ???
-!! @param[in] jm ???
+!! @param[in] im "i" dimension of the model grid tile.
+!! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn ???
 !! @param[in] jmn ???
 !! @param[in] lon_c ???
@@ -4498,7 +4498,7 @@ end function get_xnsum
 !! @param[in] delxn  ???
 !! @param[in] xnsum1 ???
 !! @param[in] xnsum2 ???
-!! @param[in] hc ???
+!! @param[out] hc Critical height.
 !! @author Jordan Alpert NOAA/EMC
       subroutine get_xnsum2(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)
@@ -4581,7 +4581,7 @@ end subroutine get_xnsum2
 !! @param[in] delxn  ???
 !! @param[in] xnsum1 ???
 !! @param[in] xnsum2 ???
-!! @param[in] hc ???
+!! @param[in] hc Critical height.
 !! @author Jordan Alpert NOAA/EMC
       subroutine get_xnsum3(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)

From 6bc0939d0c69ea2a61b852515213c03db7aca5bb Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Mon, 15 Mar 2021 20:39:05 +0000
Subject: [PATCH 10/22] Add doxygen to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Part of #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 48 +++++++++++--------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 640105687..6da3af278 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -857,7 +857,6 @@ SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
       tend=timef()
       write(6,*)' Timer 1 time= ',tend-tbeg
                                 !
-! --- CALL MAKEMT(ZAVG,ZSLM,ORO,OCLSM,mskocn,SLM,VAR,VAR4,GLAT,
       if(grid_from_file) then
        tbeg=timef()
          CALL MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,GLAT,
@@ -865,10 +864,10 @@ SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
       tend=timef()
       write(6,*)' MAKEMT2 time= ',tend-tbeg
       else
-
         CALL MAKEMT(ZAVG,ZSLM,ORO,SLM,VAR,VAR4,GLAT,
      &   IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
       endif
+
        call minmxj(IM,JM,ORO,'     ORO')
        call minmxj(IM,JM,SLM,'     SLM')
        call minmxj(IM,JM,VAR,'     VAR')
@@ -1567,25 +1566,34 @@ SUBROUTINE TERSUB(IMN,JMN,IM,JM,NM,NR,NF0,NF1,NW,EFAC,BLAT,
       RETURN
       END
 
-!> makemt
+!> Create the orography, land-mask, standard deviation of
+!! orography and the convexity on a model gaussian grid.
+!! This routine was used for the spectral GFS model.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm ???
-!! @param[in] oro  ???
-!! @param[in] slm  ???
-!! @param[in] var  ???
-!! @param[in] var4 ???
-!! @param[in] glat ???
-!! @param[in] ist ???
-!! @param[in] ien ???
-!! @param[in] jst ???
-!! @param[in] jen ???
-!! @param[in] im "i" dimension of the model grid tile.
-!! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] xlat ???
-!! @param[in] numi ???
+!! @param[in] zavg The high-resolution input orography dataset.
+!! @param[in] zslm The high-resolution input land-mask dataset.
+!! @param[out] oro Orography on the model grid.
+!! @param[out] slm Land-mask on the model grid.
+!! @param[out] var Standard deviation of orography on the model grid.
+!! @param[out] var4 Convexity on the model grid.
+!! @param[out] glat Latitude of each row of the high-resolution 
+!! orography and land-mask datasets.
+!! @param[out] ist This is the 'i' index of high-resolution data set
+!! at the east edge of the model grid cell.
+!! the high-resolution dataset with respect to the 'east' edge
+!! @param[out] ien This is the 'i' index of high-resolution data set
+!! at the west edge of the model grid cell.
+!! @param[out] jst  This is the 'j' index of high-resolution data set
+!! at the south edge of the model grid cell.
+!! @param[out] jen This is the 'j' index of high-resolution data set
+!! at the north edge of the model grid cell.
+!! @param[in] im "i" dimension of the model grid.
+!! @param[in] jm "j" dimension of the model grid.
+!! @param[in] imn "i" dimension of the hi-res input orog/mask dataset.
+!! @param[in] jmn "j" dimension of the hi-res input orog/mask dataset.
+!! @param[in] xlat The latitude of each row of the model grid.
+!! @param[in] numi For reduced gaussian grids, the number of 'i' points
+!! for each 'j' row.
 !! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEMT(ZAVG,ZSLM,ORO,SLM,VAR,VAR4,
      1 GLAT,IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)

From f3b248e90169a00389df7e1004255de79bd8bece Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 12:30:50 +0000
Subject: [PATCH 11/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 35 ++++++++++---------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 6da3af278..b59acac41 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -1829,23 +1829,26 @@ SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
 
       END   
       
-!> makemt2
+!> Create the orography, land-mask, land fraction, standard 
+!! deviation of orography and the convexity on a model 
+!! cubed-sphere tile. This routine is used for the FV3GFS model.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm ???
-!! @param[in] oro ???
-!! @param[in] slm ???
-!! @param[in] land_frac ???
-!! @param[in] var ???
-!! @param[in] var4 ???
-!! @param[in] glat ???
-!! @param[in] im "i" dimension of the model grid tile.
-!! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] lon_c ???
-!! @param[in] lat_c ???
-!! @author Jordan Alpert NOAA/EMC
+!! @param[in] zavg The high-resolution input orography dataset.
+!! @param[in] zslm The high-resolution input land-mask dataset.
+!! @param[out] oro Orography on the model tile.
+!! @param[out] slm Land-mask on the model tile.
+!! @param[out] land_frac Land fraction on the model tile.
+!! @param[out] var Standard deviation of orography on the model tile.
+!! @param[out] var4 Convexity on the model tile.
+!! @param[out] glat Latitude of each row of the high-resolution 
+!! orography and land-mask datasets.
+!! @param[in] im "i" dimension of the model grid.
+!! @param[in] jm "j" dimension of the model grid.
+!! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
+!! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
+!! @param[in] lon_c Longitude on the model tile.
+!! @param[in] lat_c Latitude on the model tile.
+!! @author GFDL Programmer
       SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
      1 GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
       implicit none

From f61d08ebd8d69501a36946edcc093ad38f07583a Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 13:11:10 +0000
Subject: [PATCH 12/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 66 +++++++++++--------
 1 file changed, 39 insertions(+), 27 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index b59acac41..d43452a0e 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -1981,24 +1981,32 @@ SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
       RETURN
       END
 
-!> makepc
+!> Make the principle coordinates - slope of orography, 
+!! anisotropy, angle of mountain range with respect to east.
+!! This routine is used for spectral GFS gaussian grids.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm ???
-!! @param[in] theta ???
-!! @param[in] gamma ???
-!! @param[in] sigma ???
-!! @param[in] glat ???
-!! @param[in] ist ???
-!! @param[in] ien ???
-!! @param[in] jst ???
-!! @param[in] jen ???
+!! @param[in] zavg The high-resolution input orography dataset.
+!! @param[in] zslm The high-resolution input land-mask dataset.
+!! @param[out] theta Angle of mountain range with respect to
+!! east for each model point.
+!! @param[out] gamma Anisotropy for each model point.
+!! @param[out] sigma Slope of orography for each model point.
+!! @param[out] glat Latitude of each row of the high-resolution 
+!! orography and land-mask datasets.
+!! @param[out] ist This is the 'i' index of high-resolution data set
+!! at the east edge of the model grid cell.
+!! the high-resolution dataset with respect to the 'east' edge
+!! @param[out] ien This is the 'i' index of high-resolution data set
+!! at the west edge of the model grid cell.
+!! @param[out] jst  This is the 'j' index of high-resolution data set
+!! at the south edge of the model grid cell.
+!! @param[out] jen This is the 'j' index of high-resolution data set
 !! @param[in] im "i" dimension of the model grid tile.
 !! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] xlat ???
-!! @param[in] numi ???
+!! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
+!! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
+!! @param[in] xlat The latitude of each row of the model grid.
+!! @param[in] numi For reduced gaussian grids, the number of 'i' points
 !! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
@@ -2255,21 +2263,25 @@ SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
       RETURN
       END
 
-!> makepc2
+!> Make the principle coordinates - slope of orography, 
+!! anisotropy, angle of mountain range with respect to east.
+!! This routine is used for the FV3GFS cubed-sphere grid.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm ???
-!! @param[in] theta ???
-!! @param[in] gamma ???
-!! @param[in] sigma ???
-!! @param[in] glat ???
+!! @param[in] zavg The high-resolution input orography dataset.
+!! @param[in] zslm The high-resolution input land-mask dataset.
+!! @param[out] theta Angle of mountain range with respect to
+!! east for each model point.
+!! @param[out] gamma Anisotropy for each model point.
+!! @param[out] sigma Slope of orography for each model point.
+!! @param[out] glat Latitude of each row of the high-resolution 
+!! orography and land-mask datasets.
 !! @param[in] im "i" dimension of the model grid tile.
 !! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] lon_c ???
-!! @param[in] lat_c ???
-!! @author Jordan Alpert NOAA/EMC
+!! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
+!! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
+!! @param[in] lon_c Longitude on the model grid tile.
+!! @param[in] lat_c Latitude on the model grid tile.
+!! @author GFDL Programmer
       SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
 C

From dd77b7ebb4fee55d6c97fb3bccbcc7930c18cd68 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 17:57:21 +0000
Subject: [PATCH 13/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f.

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 104 ++++++++++--------
 1 file changed, 61 insertions(+), 43 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index d43452a0e..813bc50d7 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -1742,18 +1742,24 @@ SUBROUTINE MAKEMT(ZAVG,ZSLM,ORO,SLM,VAR,VAR4,
       RETURN
       END
 
-!> Get index
+!> Determine the location of a cubed-sphere point within
+!! the high-resolution orography data.  The location is
+!! described by the range of i/j indices on the high-res grid.
 !!
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] npts ???
-!! @param[in] lonO ???
-!! @param[in] latO ???
-!! @param[in] delxn ???
-!! @param[out] jst ???
-!! @param[out] jen ???
-!! @param[out] ilist ???
-!! @param[out] numx ???
+!! @param[in] imn 'i' dimension of the high-resolution orography
+!! data set.
+!! @param[in] jmn 'j' dimension of the high-resolution orography
+!! data set.
+!! @param[in] npts Number of vertices to describe the cubed-sphere point.
+!! @param[in] lonO The longitudes of the cubed-sphere vertices.
+!! @param[in] latO The latitudes of the cubed-sphere vertices.
+!! @param[in] delxn Resolution of the high-resolution orography
+!! data set.
+!! @param[out] jst Starting 'j' index on the high-resolution grid.
+!! @param[out] jen Ending 'j' index on the high-resolution grid.
+!! @param[out] ilist List of 'i' indices on the high-resolution grid.
+!! @param[out] numx The number of 'i' indices on the high-resolution
+!! grid.
 !! @author GFDL programmer
       SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
      &           jst,jen,ilist,numx)
@@ -1995,18 +2001,19 @@ SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
 !! orography and land-mask datasets.
 !! @param[out] ist This is the 'i' index of high-resolution data set
 !! at the east edge of the model grid cell.
-!! the high-resolution dataset with respect to the 'east' edge
 !! @param[out] ien This is the 'i' index of high-resolution data set
 !! at the west edge of the model grid cell.
 !! @param[out] jst  This is the 'j' index of high-resolution data set
 !! at the south edge of the model grid cell.
 !! @param[out] jen This is the 'j' index of high-resolution data set
+!! at the north edge of the model grid cell.
 !! @param[in] im "i" dimension of the model grid tile.
 !! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
 !! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
 !! @param[in] xlat The latitude of each row of the model grid.
 !! @param[in] numi For reduced gaussian grids, the number of 'i' points
+!! for each 'j' row.
 !! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IST,IEN,JST,JEN,IM,JM,IMN,JMN,XLAT,numi)
@@ -2515,32 +2522,42 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
       RETURN
       END
       
-!> makeoa
+!> Create orographic asymmetry and orographic length scale on
+!! the model grid.  This routine is used for the spectral
+!! GFS gaussian grid.
 !!
-!! @param[in] zavg ???
-!! @param[in] var ???
+!! @param[in] zavg The high-resolution input orography dataset.
+!! @param[in] var Standard deviation of orography on the model grid.
 !! @param[out] glat Latitude of each row of input terrain dataset.
-!! @param[in] oa4 ???
-!! @param[in] ol ???
-!! @param[in] ioa4 ???
-!! @param[in] elvmax ???
-!! @param[in] oro ???
-!! @param[in] oro1 ???
-!! @param[in] xnsum ???
+!! @param[out] oa4 Orographic asymmetry on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ol Orographic length scale on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ioa4 Count of oa4 values between certain thresholds.
+!! @param[out] elvmax Maximum elevation on the model grid.
+!! @param[in] oro Orography on the model grid.
+!! @param[out] oro1 Save array for model grid orography.
+!! @param[out] xnsum Number of high-resolution orography points
+!! higher than the model grid box average.
 !! @param[in] xnsum1 ???
 !! @param[in] xnsum2 ???
 !! @param[in] xnsum3 ???
 !! @param[in] xnsum4 ???
-!! @param[in] ist ???
-!! @param[in] ien ???
-!! @param[in] jst ???
-!! @param[in] jen ???
-!! @param[in] im "i" dimension of the model grid tile.
-!! @param[in] jm "j" dimension of the model grid tile.
+!! @param[out] ist This is the 'i' index of high-resolution data set
+!! at the east edge of the model grid cell.
+!! @param[out] ien This is the 'i' index of high-resolution data set
+!! at the west edge of the model grid cell.
+!! @param[out] jst  This is the 'j' index of high-resolution data set
+!! at the south edge of the model grid cell.
+!! @param[out] jen This is the 'j' index of high-resolution data set
+!! at the north edge of the model grid cell.
+!! @param[in] im "i" dimension of the model grid.
+!! @param[in] jm "j" dimension of the model grid.
 !! @param[in] imn "i" dimension of the input terrain dataset.
 !! @param[in] jmn "j" dimension of the input terrain dataset.
-!! @param[in] xlat ???
-!! @param[in] numi ???
+!! @param[in] xlat The latitude of each row of the model grid.
+!! @param[in] numi For reduced gaussian grids, the number of 'i' points
+!! for each 'j' row.
 !! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEOA(ZAVG,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
@@ -4264,12 +4281,12 @@ SUBROUTINE minmaxj(IM,JM,A,title)
       
 !> Convert from latitude and longitude to x,y,z coordinates.
 !!
-!! @param[in] siz ???
-!! @param[in] lon ???
-!! @param[in] lat ???
-!! @param[out] x ???
-!! @param[out] y ???
-!! @param[out] z ???
+!! @param[in] siz Number of points to convert.
+!! @param[in] lon Longitude of points to convert.
+!! @param[in] lat Latitude of points to convert.
+!! @param[out] x 'x' coordinate of the converted points.
+!! @param[out] y 'y' coordinate of the converted points.
+!! @param[out] z 'z' coordinate of the converted points.
 !! @author GFDL programmer
       subroutine latlon2xyz(siz,lon, lat, x, y, z)
       implicit none
@@ -4333,14 +4350,15 @@ FUNCTION spherical_angle(v1, v2, v3)
         return
       END  
       
-!> Check to see if a point is inside a polygon.
+!> Check if a point is inside a polygon.
 !!
-!! @param[in] lon1 ???
-!! @param[in] lat1 ???
-!! @param[in] npts ???
-!! @param[in] lon2 ???
-!! @param[in] lat2 ???
-!! @return inside_a_polygon ???
+!! @param[in] lon1 Longitude of the point to check.
+!! @param[in] lat1 Latitude of the point to check.
+!! @param[in] npts Number of polygon vertices.
+!! @param[in] lon2 Longitude of the polygon vertices.
+!! @param[in] lat2 Latitude of the polygon vertices.
+!! @return inside_a_polygon When true, point is within
+!! the polygon.
 !! @author GFDL programmer
       FUNCTION inside_a_polygon(lon1, lat1, npts, lon2, lat2)
         implicit none

From b36df6284bf13af8cb2376138e520536c1c7ba62 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 19:16:19 +0000
Subject: [PATCH 14/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 68 ++++++++++---------
 1 file changed, 37 insertions(+), 31 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 813bc50d7..c1779f66a 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -1852,8 +1852,8 @@ SUBROUTINE get_index(IMN,JMN,npts,lonO,latO,DELXN,
 !! @param[in] jm "j" dimension of the model grid.
 !! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
 !! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
-!! @param[in] lon_c Longitude on the model tile.
-!! @param[in] lat_c Latitude on the model tile.
+!! @param[in] lon_c Longitude of the model grid corner points.
+!! @param[in] lat_c Latitude on the model grid corner points.
 !! @author GFDL Programmer
       SUBROUTINE MAKEMT2(ZAVG,ZSLM,ORO,SLM,land_frac,VAR,VAR4,
      1 GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
@@ -2286,8 +2286,8 @@ SUBROUTINE MAKEPC(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
 !! @param[in] jm "j" dimension of the model grid tile.
 !! @param[in] imn "i" dimension of the hi-res input orog/mask datasets.
 !! @param[in] jmn "j" dimension of the hi-res input orog/mask datasets.
-!! @param[in] lon_c Longitude on the model grid tile.
-!! @param[in] lat_c Latitude on the model grid tile.
+!! @param[in] lon_c Longitude of model grid corner points.
+!! @param[in] lat_c Latitude of the model grid corner points.
 !! @author GFDL Programmer
       SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
      1           GLAT,IM,JM,IMN,JMN,lon_c,lat_c)
@@ -2913,36 +2913,42 @@ function get_lat_angle(dy, DEGRAD)
          
       end function get_lat_angle
       
-!> makeoa2
+!> Create orographic asymmetry and orographic length scale on
+!! the model grid.  This routine is used for the spectral
+!! GFS gaussian grid.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm  ???
-!! @param[in] var ???
-!! @param[in] glat ???
-!! @param[in] oa4 ???
-!! @param[in] ol ???
-!! @param[in] ioa4 ???
-!! @param[in] elvmax ???
-!! @param[in] oro ???
-!! @param[in] oro1 ???
-!! @param[in] xnsum ???
-!! @param[in] xnsum1 ???
-!! @param[in] xnsum2 ???
-!! @param[in] xnsum3 ???
-!! @param[in] xnsum4, ???
+!! @param[in] zavg High-resolution orography data.
+!! @param[in] zslm High-resolution land-mask data.
+!! @param[in] var Standard deviation of orography on the model grid.
+!! @param[out] glat Latitude of each row of input terrain dataset.
+!! @param[out] oa4 Orographic asymmetry on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ol Orographic length scale on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ioa4 Count of oa4 values between certain thresholds.
+!! @param[out] elvmax Maximum elevation within a model grid box.
+!! @param[in] oro Orography on the model grid.
+!! @param[out] oro1 Save array for model grid orography.
+!! @param[out] xnsum Not used.
+!! @param[out] xnsum1 Not used.
+!! @param[out] xnsum2 Not used.
+!! @param[out] xnsum3 Not used.
+!! @param[out] xnsum4 Not used.
 !! @param[in] im "i" dimension of the model grid tile.
 !! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] lon_c ???
-!! @param[in] lat_c ???
-!! @param[in] lon_t ???
-!! @param[in] lat_t ???
-!! @param[in] dx ???
-!! @param[in] dy ???
-!! @param[in] is_south_pole ???
-!! @param[in] is_north_pole ???
-!! @author Jordan Alpert NOAA/EMC
+!! @param[in] imn "i" dimension of the high-resolution orography and
+!! mask data.
+!! @param[in] jmn "j" dimension of the high-resolution orography and
+!! mask data.
+!! @param[in] lon_c Corner point longitudes of the model grid points.
+!! @param[in] lat_c Corner point latitudes of the model grid points.
+!! @param[in] lon_t Center point longitudes of the model grid points.
+!! @param[in] lat_t Center point latitudes of the model grid points.
+!! @param[in] dx Length of model grid points in the 'x' direction.
+!! @param[in] dy Length of model grid points in the 'y' direction.
+!! @param[in] is_south_pole Is the model point at the south pole?
+!! @param[in] is_north_pole is the model point at the north pole?
+!! @author GFDL Programmer
       SUBROUTINE MAKEOA2(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
      2           IM,JM,IMN,JMN,lon_c,lat_c,lon_t,lat_t,dx,dy,

From e0a5bc29492f9425992be41ac0fb4ee0b72540f9 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 19:44:46 +0000
Subject: [PATCH 15/22] More doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 36 ++++++++++---------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index c1779f66a..6d158c33f 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -2876,14 +2876,16 @@ SUBROUTINE MAKEOA(ZAVG,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       WRITE(6,*) "! MAKEOA EXIT"
 C
       RETURN
-      END
+      END SUBROUTINE MAKEOA
 
-!> Get longitude angle
+!> Convert the 'x' direction distance of a cubed-sphere grid
+!! point to the corresponding distance in longitude.
 !!
-!! @param[in] dx ???
-!! @param[in] lat ???
-!! @param[in] degrad ???
-!! @return get_lon_angle Longitude angle.
+!! @param[in] dx Distance along the 'x' direction of a 
+!! cubed-sphere grid point.
+!! @param[in] lat Latitude of the cubed-sphere point.
+!! @param[in] degrad  Conversion from radians to degrees.
+!! @return get_lon_angle Corresponding distance in longitude.
 !! @author GFDL programmer
       function get_lon_angle(dx,lat, DEGRAD)
       implicit none
@@ -2896,11 +2898,13 @@ function get_lon_angle(dx,lat, DEGRAD)
          
       end function get_lon_angle
 
-!> Get latitude angle
+!> Convert the 'y' direction distance of a cubed-sphere grid
+!! point to the corresponding distance in latitude.
 !!
-!! @param[in] dy ???
-!! @param[in] degrad ???
-!! @return get_lat_angle ???
+!! @param[in] dy Distance along the 'y' direction of a cubed-sphere
+!! point.
+!! @param[in] degrad Conversion from radians to degrees.
+!! @return get_lat_angle Corresponding distance in latitude.
 !! @author GFDL programmer
       function get_lat_angle(dy, DEGRAD)
       implicit none
@@ -3333,14 +3337,14 @@ SUBROUTINE MAKEOA2(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       WRITE(6,*) "! MAKEOA2 EXIT"
 C
       RETURN
-      END
+      END SUBROUTINE MAKEOA2
  
-!> Compute a great circle distance
+!> Compute a great circle distance between two points.
 !!
-!! @param[in] theta1 ???
-!! @param[in] phi1 ???
-!! @param[in] theta2 ???
-!! @param[in] phi2 ???
+!! @param[in] theta1 Longitude of point 1.
+!! @param[in] phi1 Latitude of point 1.
+!! @param[in] theta2 Longitude of point 2.
+!! @param[in] phi2 Latitude of point2.
 !! @return spherical_distance Great circle distance.
 !! @author GFDL programmer
       function spherical_distance(theta1,phi1,theta2,phi2)

From afd9cffa3022b0f6d6d978f17ea7ff2ab42e9093 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 16 Mar 2021 21:00:33 +0000
Subject: [PATCH 16/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 92 +++++++++++--------
 1 file changed, 52 insertions(+), 40 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 6d158c33f..1d255d7fb 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -2520,7 +2520,7 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
       WRITE(6,*) "! MAKE Principal Coord  DONE"
 C
       RETURN
-      END
+      END SUBROUTINE MAKEPC2
       
 !> Create orographic asymmetry and orographic length scale on
 !! the model grid.  This routine is used for the spectral
@@ -2539,10 +2539,14 @@ SUBROUTINE MAKEPC2(ZAVG,ZSLM,THETA,GAMMA,SIGMA,
 !! @param[out] oro1 Save array for model grid orography.
 !! @param[out] xnsum Number of high-resolution orography points
 !! higher than the model grid box average.
-!! @param[in] xnsum1 ???
-!! @param[in] xnsum2 ???
-!! @param[in] xnsum3 ???
-!! @param[in] xnsum4 ???
+!! @param[out] xnsum1 Number of high-resolution orography points
+!! higher than the critical height.
+!! @param[out] xnsum2 Total number of high-resolution orography points
+!! within a model grid box.
+!! @param[out] xnsum3 Same as xnsum1, except shifted by half a 
+!! model grid box.
+!! @param[out] xnsum4 Same as xnsum2, except shifted by half a
+!! model grid box.
 !! @param[out] ist This is the 'i' index of high-resolution data set
 !! at the east edge of the model grid cell.
 !! @param[out] ien This is the 'i' index of high-resolution data set
@@ -2918,8 +2922,8 @@ function get_lat_angle(dy, DEGRAD)
       end function get_lat_angle
       
 !> Create orographic asymmetry and orographic length scale on
-!! the model grid.  This routine is used for the spectral
-!! GFS gaussian grid.
+!! the model grid.  This routine is used for the cubed-sphere
+!! grid.
 !!
 !! @param[in] zavg High-resolution orography data.
 !! @param[in] zslm High-resolution land-mask data.
@@ -3470,41 +3474,49 @@ subroutine interpolate_mismatch(im_in, jm_in, data_in,
 
       end subroutine interpolate_mismatch
       
-!> Makeoa3
+!> Create orographic asymmetry and orographic length scale on
+!! the model grid. This routine is used for the cubed-sphere
+!! grid. The asymmetry and length scales are interpolated
+!! from an existing gfs orography file. The maximum elevation
+!! is computed from the high-resolution orography data.
 !!
-!! @param[in] zavg ???
-!! @param[in] zslm ???
-!! @param[in] var ???
-!! @param[in] glat ???
-!! @param[in] oa4 ???
-!! @param[in] ol ???
-!! @param[in] ioa4 ???
-!! @param[in] elvmax ???
-!! @param[in] oro ???
-!! @param[in] slm ???
-!! @param[in] oro1 ???
-!! @param[in] xnsum ???
-!! @param[in] xnsum1 ???
-!! @param[in] xnsum2 ???
-!! @param[in] xnsum3 ???
-!! @param[in] xnsum4 ???
+!! @param[in] zavg High-resolution orography data.
+!! @param[in] zslm High-resolution land-mask data.  Not used.
+!! @param[in] var Standard deviation of orography on the model grid.
+!! @param[out] glat Latitude of each row of input terrain dataset.
+!! @param[out] oa4 Orographic asymmetry on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ol Orographic length scale on the model grid. Four
+!! directional components - W/S/SW/NW
+!! @param[out] ioa4 Count of oa4 values between certain thresholds.
+!! @param[out] elvmax Maximum elevation within a model grid box.
+!! @param[in] slm Land-mask on model grid.
+!! @param[in] oro Orography on the model grid.
+!! @param[out] oro1 Save array for model grid orography.
+!! @param[in] xnsum Not used.
+!! @param[in] xnsum1 Not used.
+!! @param[in] xnsum2 Not used.
+!! @param[in] xnsum3 Not used.
+!! @param[in] xnsum4 Not used.
 !! @param[in] im "i" dimension of the model grid tile.
 !! @param[in] jm "j" dimension of the model grid tile.
-!! @param[in] imn ???
-!! @param[in] jmn ???
-!! @param[in] lon_c ???
-!! @param[in] lat_c ???
-!! @param[in] lon_t ???
-!! @param[in] lat_t ???
-!! @param[in] is_south_pole ???
-!! @param[in] is_north_pole ???
-!! @param[in] imi ???
-!! @param[in] jmi ???
-!! @param[in] oa_in ???
-!! @param[in] ol_in ???
-!! @param[in] slm_in ???
-!! @param[in] lon_in ???
-!! @param[in] lat_in ???
+!! @param[in] imn "i" dimension of the high-resolution orography and
+!! mask data.
+!! @param[in] jmn "j" dimension of the high-resolution orography and
+!! mask data.
+!! @param[in] lon_c Corner point longitudes of the model grid points.
+!! @param[in] lat_c Corner point latitudes of the model grid points.
+!! @param[in] lon_t Center point longitudes of the model grid points.
+!! @param[in] lat_t Center point latitudes of the model grid points.
+!! @param[in] is_south_pole Not used.
+!! @param[in] is_north_pole Not used.
+!! @param[in] imi 'i' dimension of input gfs orography data.
+!! @param[in] jmi 'j' dimension of input gfs orography data.
+!! @param[in] oa_in Asymmetry on the input gfs orography data.
+!! @param[in] ol_in Length scales on the input gfs orography data.
+!! @param[in] slm_in Land-sea mask on the input gfs orography data.
+!! @param[in] lon_in Longitude on the input gfs orography data.
+!! @param[in] lat_in Latitude on the input gfs orography data.
 !! @author Jordan Alpert NOAA/EMC
       SUBROUTINE MAKEOA3(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
      1           ORO,SLM,oro1,XNSUM,XNSUM1,XNSUM2,XNSUM3,XNSUM4,
@@ -3889,7 +3901,7 @@ SUBROUTINE MAKEOA3(ZAVG,zslm,VAR,GLAT,OA4,OL,IOA4,ELVMAX,
       WRITE(6,*) "! MAKEOA3 EXIT"
 C
       RETURN
-      END
+      END SUBROUTINE MAKEOA3
       
 !> Reverse the east-west and north-south axes
 !! in a two-dimensional array.

From 6f3b082d6a33220d50af9ede2fb1b836348428bd Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 17 Mar 2021 14:46:55 +0000
Subject: [PATCH 17/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 31 ++++++++++---------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 1d255d7fb..47f849e56 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -3370,18 +3370,21 @@ function spherical_distance(theta1,phi1,theta2,phi2)
 
       end function spherical_distance
       
-!> Get mismatch index
+!> For unmapped land points, find the nearest land point
+!! on the input data and pass back its i/j index.
 !!
-!! @param[in] im_in ???
-!! @param[in] jm_in ???
-!! @param[in] geolon_in ???
-!! @param[in] geolat_in ???
-!! @param[in] bitmap_in ???
-!! @param[in] num_out ???
-!! @param[in] lon_out ???
-!! @param[in] lat_out ???
-!! @param[out] iindx ???
-!! @param[out] jindx ???
+!! @param[in] im_in 'i' dimension of input data.
+!! @param[in] jm_in 'j' dimension of input data.
+!! @param[in] geolon_in Longitude of input data.
+!! @param[in] geolat_in Latitude of input data.
+!! @param[in] bitmap_in Bitmap (mask) of input data.
+!! @param[in] num_out Number of unmapped points.
+!! @param[in] lon_out Longitude of unmapped points.
+!! @param[in] lat_out Latitude of unmapped points.
+!! @param[out] iindx 'i' indices of nearest land points
+!! on the input data.
+!! @param[out] jindx 'j' indices of nearest land points
+!! on the input data.
 !! @author GFDL progammer
       subroutine get_mismatch_index(im_in, jm_in, geolon_in,geolat_in,
      &           bitmap_in,num_out, lon_out,lat_out, iindx, jindx )
@@ -4327,9 +4330,9 @@ subroutine latlon2xyz(siz,lon, lat, x, y, z)
 
 !> Compute spherical angle.
 !!
-!! @param[in] v1 ???
-!! @param[in] v2 ???
-!! @param[in] v3 ???
+!! @param[in] v1 Vector 1.
+!! @param[in] v2 Vector 2.
+!! @param[in] v3 Vector 3.
 !! @return spherical_angle Spherical Angle.
 !! @author GFDL programmer
       FUNCTION spherical_angle(v1, v2, v3)

From 8428a32d8766781f45799ba798adc53b443e23dc Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 17 Mar 2021 15:15:00 +0000
Subject: [PATCH 18/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 47f849e56..883ccdd8d 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -3454,15 +3454,18 @@ subroutine get_mismatch_index(im_in, jm_in, geolon_in,geolat_in,
 
       end subroutine get_mismatch_index
       
-!> Interpolate mismatch
+!> Replace unmapped model land points with the nearest land point on the
+!! input grid.
 !!
-!! @param[in] im_in ???
-!! @param[in] jm_in ???
-!! @param[in] data_in ???
-!! @param[in] num_out ???
-!! @param[out] data_out ???
-!! @param[in] iindx ???
-!! @param[in] jindx ???
+!! @param[in] im_in 'i' dimension of input grid.
+!! @param[in] jm_in 'j' dimension of input grid.
+!! @param[in] data_in Input grid data.
+!! @param[in] num_out Number of unmapped model points.
+!! @param[out] data_out Data on the model tile.
+!! @param[in] iindx 'i' indices of the nearest land points on
+!! the input grid.
+!! @param[in] jindx 'j' indices of the nearest land points on
+!! the input grid.
 !! @author GFDL programmer
       subroutine interpolate_mismatch(im_in, jm_in, data_in,
      &                                num_out, data_out, iindx, jindx)

From 20e85f0c6867922270754b33cffd0137d7a369d3 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 17 Mar 2021 15:38:39 +0000
Subject: [PATCH 19/22] Doxygen updates to ./orog.fd/mtnlm7_oclsm.f

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 35 ++++++++++++-------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 883ccdd8d..5074c6121 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -4460,20 +4460,29 @@ FUNCTION inside_a_polygon(lon1, lat1, npts, lon2, lat2)
         
       end
 
-!> Get xnsum
+!> Count the number of high-resolution orography points that
+!! are higher than the model grid box average orography height.
 !!
-!! @param[in] lon1  ???
-!! @param[in] lat1  ???
-!! @param[in] lon2  ???
-!! @param[in] lat2  ???
-!! @param[in] imn   ???
-!! @param[in] jmn   ??? 
-!! @param[in] glat  ???
-!! @param[in] zavg  ???
-!! @param[in] zslm  ???
-!! @param[in] delxn  ???
-!! @return get_xnsum ???
-!! @author Jordan Alpert NOAA/EMC
+!! @param[in] lon1 Longitude of corner point 1 of the model 
+!! grid box.
+!! @param[in] lat1 Latitude of corner point 1 of the model
+!! grid box.
+!! @param[in] lon2 Longitude of corner point 2 of the model
+!! grid box.
+!! @param[in] lat2 Latitude of corner point 2 of the model
+!! grid box.
+!! @param[in] imn 'i' dimension of the high-resolution orography
+!! data.
+!! @param[in] jmn 'j' dimension of the high-resolution orography
+!! data.
+!! @param[in] glat Latitude of each row of the high-resolution
+!! orography data.
+!! @param[in] zavg The high-resolution orography.
+!! @param[in] zslm  The high-resolution land mask.
+!! @param[in] delxn Resolution of the high-res orography data.
+!! @return get_xnsum The number of high-res points above the
+!! mean orography.
+!! @author GFDL Programmer
       function get_xnsum(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn)
         implicit none

From 5378c7335f3d733677dd775db0e616b2892b07b4 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 17 Mar 2021 19:21:05 +0000
Subject: [PATCH 20/22] Doxygen updates to ./lake.fd/lakefrac.F90 and
 ./orog.fd/mtnlm7_oclsm.f.

Part of #191
Fixes #344
Fixes #408
---
 sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90  | 73 +++++++++-------
 .../orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f | 83 ++++++++++++-------
 2 files changed, 97 insertions(+), 59 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90 b/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
index a419f8c1f..fada9cd2b 100644
--- a/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
+++ b/sorc/orog_mask_tools.fd/lake.fd/lakefrac.F90
@@ -133,12 +133,13 @@ PROGRAM lake_frac
     STOP
 CONTAINS
 
-!> Calculate lake fraction depth
+!> Calculate lake fraction and depth on the model grid from
+!! high-resolution data.
 !!
-!! @param[in] lakestat ???
-!! @param[in] lakedpth ???
-!! @param[out] cs_lakestat ???
-!! @param[out] cs_lakedpth ???
+!! @param[in] lakestat High-resolution lake status code.
+!! @param[in] lakedpth High-resolution lake depth.
+!! @param[out] cs_lakestat Lake fraction on the model grid.
+!! @param[out] cs_lakedpth Lake depth on the model grid.
 !! @author Ning Wang
 SUBROUTINE cal_lake_frac_depth(lakestat,cs_lakestat,lakedpth,cs_lakedpth)
     INTEGER*1, INTENT(IN) :: lakestat(:)
@@ -369,10 +370,14 @@ SUBROUTINE cal_lake_frac_depth(lakestat,cs_lakestat,lakedpth,cs_lakedpth)
 
 END SUBROUTINE cal_lake_frac_depth 
 
-!> Read cubed sphere grid
+!> Read the latitude and longitude for a cubed-sphere
+!! grid from the 'grid' files. For global grids, all
+!! six sides are returned.
 !!
-!! @param[in] res ???
-!! @param[out] grid ???
+!! @param[in] res The resolution. Example: '96' for C96.
+!! @param[out] grid Array containing the latitude and
+!! longitude on the 'supergrid'.  Multiple tiles
+!! are concatenated.
 !! @author Ning Wang
 SUBROUTINE read_cubed_sphere_grid(res, grid) 
     INTEGER, INTENT(IN) :: res
@@ -426,13 +431,14 @@ SUBROUTINE read_cubed_sphere_grid(res, grid)
 
 END SUBROUTINE read_cubed_sphere_grid
 
-!> Read cubed sphere reg grid
+!> Read the latitude and longitude for a regional grid
+!! from the 'grid' file. 
 !!
-!! @param[in] res ???
-!! @param[out] grid ???
-!! @param[in] halo_depth ???
-!! @param[out] res_x ???
-!! @param[out] res_y ???
+!! @param[in] res Resolution of grid.  Example: '96' for C96.
+!! @param[out] grid Latitude and longitude on the supergrid.
+!! @param[in] halo_depth Lateral halo. Not used.
+!! @param[out] res_x Number of grid points in the 'x' direction.
+!! @param[out] res_y Number of grid points in the 'y' direction.
 !! @author Ning Wang
 SUBROUTINE read_cubed_sphere_reg_grid(res, grid, halo_depth, res_x, res_y) 
     INTEGER, INTENT(IN) :: res, halo_depth
@@ -494,13 +500,16 @@ SUBROUTINE read_cubed_sphere_reg_grid(res, grid, halo_depth, res_x, res_y)
 
 END SUBROUTINE read_cubed_sphere_reg_grid
 
-!> Read lake data
+!> Read a high-resolution lake depth dataset, and a corresponding 
+!! lake status dataset which provides a status code on the
+!! reliability of each lake depth point.
 !!
-!! @param[in] lakedata_path ???
-!! @param[out] lake_stat ???
-!! @param[out] lake_dpth ???
-!! @param[in] nlat ???
-!! @param[in] nlon ???
+!! @param[in] lakedata_path Path to the lake depth and lake status
+!! dataset.
+!! @param[out] lake_stat Status code.
+!! @param[out] lake_dpth Lake depth.
+!! @param[in] nlat 'j' dimension of both datasets.
+!! @param[in] nlon 'i' dimension of both datasets.
 SUBROUTINE read_lakedata(lakedata_path,lake_stat,lake_dpth,nlat,nlon)
     CHARACTER(len=256), INTENT(IN) :: lakedata_path
     INTEGER*1, INTENT(OUT) :: lake_stat(:)
@@ -525,11 +534,13 @@ SUBROUTINE read_lakedata(lakedata_path,lake_stat,lake_dpth,nlat,nlon)
 
 END SUBROUTINE read_lakedata
    
-!> Write lake data to oro data.
+!> Write lake depth and fraction to an existing model orography file.
+!! Also, perform some quality control checks on the lake data.
+!! This routine is used for non-regional grids.
 !!
-!! @param[in] cs_res ???
-!! @param[in] cs_lakestat ???
-!! @param[in] cs_lakedpth ???
+!! @param[in] cs_res Resolution. Example: '96' for C96.
+!! @param[in] cs_lakestat Lake fraction.
+!! @param[in] cs_lakedpth Lake depth.
 !! @author Ning Wang
 SUBROUTINE write_lakedata_to_orodata(cs_res, cs_lakestat, cs_lakedpth) 
     USE netcdf 
@@ -720,13 +731,15 @@ SUBROUTINE write_lakedata_to_orodata(cs_res, cs_lakestat, cs_lakedpth)
   
 END SUBROUTINE write_lakedata_to_orodata
 
-!> write reg lake data to oro data.
+!> Write lake depth and fraction to an existing model orography file.
+!! Also, perform some quality control checks on the lake data.
+!! This routine is used for regional grids.
 !!
-!! @param[in] cs_res ???
-!! @param[in] tile_x_dim ???
-!! @param[in] tile_y_dim ???
-!! @param[in] cs_lakestat ???
-!! @param[in] cs_lakedpth ???
+!! @param[in] cs_res Resolution. Example: '96' for C96.
+!! @param[in] cs_lakestat Lake fraction.
+!! @param[in] cs_lakedpth Lake depth.
+!! @param[in] tile_x_dim 'x' dimension of the model grid.
+!! @param[in] tile_y_dim 'y' dimension of the model grid.
 !! @author Ning Wang
 SUBROUTINE write_reg_lakedata_to_orodata(cs_res, tile_x_dim, tile_y_dim, cs_lakestat, cs_lakedpth) 
     USE netcdf 
diff --git a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
index 5074c6121..eb95aac84 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
+++ b/sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f
@@ -172,7 +172,7 @@
 !! @param[in] NR Rhomboidal flag.
 !! @param[in] NF0 First order spectral filter parameters.
 !! @param[in] NF1 Second order spectral filter parameters.
-!! @param[in] NW ???
+!! @param[in] NW Number of waves.
 !! @param[in] EFAC Factor to adjust orography by its variance.
 !! @param[in] BLAT When less than zero, reverse latitude/
 !! longitude for output.
@@ -4562,22 +4562,34 @@ function get_xnsum(lon1,lat1,lon2,lat2,IMN,JMN,
          
       end function get_xnsum  
       
-!> Get xnnum2
+!> Count the number of high-resolution orography points that
+!! are higher than a critical value inside a model grid box
+!! (or a portion of a model grid box). The critical value is a 
+!! function of the standard deviation of orography.
 !!
-!! @param[in] lon1  ???
-!! @param[in] lat1  ???
-!! @param[in] lon2  ???
-!! @param[in] lat2  ???
-!! @param[in] imn   ???
-!! @param[in] jmn   ??? 
-!! @param[in] glat  ???
-!! @param[in] zavg  ???
-!! @param[in] zslm  ???
-!! @param[in] delxn  ???
-!! @param[in] xnsum1 ???
-!! @param[in] xnsum2 ???
+!! @param[in] lon1 Longitude of corner point 1 of the model 
+!! grid box.
+!! @param[in] lat1 Latitude of corner point 1 of the model
+!! grid box.
+!! @param[in] lon2 Longitude of corner point 2 of the model
+!! grid box.
+!! @param[in] lat2 Latitude of corner point 2 of the model
+!! grid box.
+!! @param[in] imn 'i' dimension of the high-resolution orography
+!! data.
+!! @param[in] jmn 'j' dimension of the high-resolution orography
+!! data.
+!! @param[in] glat Latitude of each row of the high-resolution
+!! orography data.
+!! @param[in] zavg The high-resolution orography.
+!! @param[in] zslm  The high-resolution land mask.
+!! @param[in] delxn Resolution of the high-res orography data.
+!! @param[out] xnsum1 The number of high-resolution orography
+!! above the critical value inside a model grid box.
+!! @param[out] xnsum2 The number of high-resolution orography
+!! points inside a model grid box.
 !! @param[out] hc Critical height.
-!! @author Jordan Alpert NOAA/EMC
+!! @author GFDL Programmer
       subroutine get_xnsum2(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)
         implicit none
@@ -4645,22 +4657,35 @@ subroutine get_xnsum2(lon1,lat1,lon2,lat2,IMN,JMN,
          
       end subroutine get_xnsum2 
 
-!> Get xnnum3
+!> Count the number of high-resolution orography points that
+!! are higher than a critical value inside a model grid box
+!! (or a portion of a model grid box). Unlike routine
+!! get_xnsum2(), this routine does not compute the critical
+!! value. Rather, it is passed in.
 !!
-!! @param[in] lon1  ???
-!! @param[in] lat1  ???
-!! @param[in] lon2  ???
-!! @param[in] lat2  ???
-!! @param[in] imn   ???
-!! @param[in] jmn   ??? 
-!! @param[in] glat  ???
-!! @param[in] zavg  ???
-!! @param[in] zslm  ???
-!! @param[in] delxn  ???
-!! @param[in] xnsum1 ???
-!! @param[in] xnsum2 ???
+!! @param[in] lon1 Longitude of corner point 1 of the model 
+!! grid box.
+!! @param[in] lat1 Latitude of corner point 1 of the model
+!! grid box.
+!! @param[in] lon2 Longitude of corner point 2 of the model
+!! grid box.
+!! @param[in] lat2 Latitude of corner point 2 of the model
+!! grid box.
+!! @param[in] imn 'i' dimension of the high-resolution orography
+!! data.
+!! @param[in] jmn 'j' dimension of the high-resolution orography
+!! data.
+!! @param[in] glat Latitude of each row of the high-resolution
+!! orography data.
+!! @param[in] zavg The high-resolution orography.
+!! @param[in] zslm  The high-resolution land mask.
+!! @param[in] delxn Resolution of the high-res orography data.
+!! @param[out] xnsum1 The number of high-resolution orography
+!! above the critical value inside a model grid box.
+!! @param[out] xnsum2 The number of high-resolution orography
+!! points inside a model grid box.
 !! @param[in] hc Critical height.
-!! @author Jordan Alpert NOAA/EMC
+!! @author GFDL Programmer
       subroutine get_xnsum3(lon1,lat1,lon2,lat2,IMN,JMN,
      &                   glat,zavg,zslm,delxn,xnsum1,xnsum2,HC)
         implicit none

From a05f8bb1914f072bcaeae8aa7c4f65842211e697 Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Wed, 17 Mar 2021 20:37:15 +0000
Subject: [PATCH 21/22] Doxygen updates to ./lake.fd/find_limit.F90

Part of #191
Fixes #344
Fixes #408
---
 .../orog_mask_tools.fd/lake.fd/find_limit.F90 | 29 ++++++++++---------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90 b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
index 9c871ce34..5a2bfbd9e 100644
--- a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
+++ b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
@@ -1,13 +1,15 @@
 !> @file
-!! @brief Find limit
+!! @brief Geo-reference utilities for a cubed-sphere grid.
 !! @author Ning Wang
 
-!> Find limit
+!> Given two points on a cubed-sphere grid, compute the
+!! maximum and minimum latitudinal extent of the 
+!! resulting great circle.
 !!
-!! @param[in] p1_in ???
-!! @param[in] p2_in ???
-!! @param[out] latmin ???
-!! @param[out] latmax ???
+!! @param[in] p1_in Latitude and longitude of point 1.
+!! @param[in] p2_in Latitude and longitude of point 2.
+!! @param[out] latmin Minimum latitudinal extent.
+!! @param[out] latmax Maximum latitudinal extent.
 !! @author Ning Wang
 !#define DIAG
 SUBROUTINE find_limit (p1_in, p2_in, latmin, latmax)
@@ -47,13 +49,12 @@ SUBROUTINE find_limit (p1_in, p2_in, latmin, latmax)
 
 END SUBROUTINE find_limit
 
-!>
-!!  This subroutine computes the latitude and longitude 
-!!  of the middle point between two given ponits.
+!> Compute the latitude and longitude of the middle
+!! point between two given points.
 !!
-!!  There are two formulae available to compute it.
+!! There are two formulae available to compute it.
 !!  
-!!  One derived from a more general m-sect formula:
+!! One derived from a more general m-sect formula:
 !!  <pre>
 !!  xyz = sin((1-f)*theta) / sin(theta) * xyz1 +
 !!        sin(f*theta) /sin(theta) * xyz2 ;
@@ -64,14 +65,14 @@ END SUBROUTINE find_limit
 !!  xyz = 0.5 / sqrt[(1+dot(xyz1,xyz2))/2] * (xyz1+xyz2)
 !!  </pre>
 !!
-!!  and the other one is the normalized middle point of
-!!  the two end points:
+!! and the other one is the normalized middle point of
+!! the two end points:
 !!
 !!  <pre>
 !!  xyz = 0.5 * (xyz1+xyz2), xyz = xyz / sqrt(dot(xyz,xyz))
 !!  </pre>
 !!
-!!  @author Ning Wang @date March, 2006
+!! @author Ning Wang @date March, 2006
 !!
 SUBROUTINE middle(p1,p2,p)
      IMPLICIT NONE

From f4066c8b2290c290aaf91bc75ba86f613facce4f Mon Sep 17 00:00:00 2001
From: George Gayno <George.Gayno@noaa.gov>
Date: Tue, 23 Mar 2021 19:24:26 +0000
Subject: [PATCH 22/22] Doxygen update to ./lake.fd/find_limit.F90

Part of #191
Fixes #344
Fixes #408
---
 sorc/orog_mask_tools.fd/lake.fd/find_limit.F90 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90 b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
index 5a2bfbd9e..0e4b3cfe1 100644
--- a/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
+++ b/sorc/orog_mask_tools.fd/lake.fd/find_limit.F90
@@ -72,8 +72,10 @@ END SUBROUTINE find_limit
 !!  xyz = 0.5 * (xyz1+xyz2), xyz = xyz / sqrt(dot(xyz,xyz))
 !!  </pre>
 !!
+!! @param[in] p1 Latitude/longitude of first end point.
+!! @param[in] p2 Latitude/longitude of second end point
+!! @param[out] p Latitude/longitude of the mid-point.
 !! @author Ning Wang @date March, 2006
-!!
 SUBROUTINE middle(p1,p2,p)
      IMPLICIT NONE