Cleanup the landing page of each utility's documentation (ufs-communi…

…ty#429)

* cleanup of user_guides

* landing page cleanup

* fixed some doxygen warnings

* added some code authors to the README

* fixed driver.f90 reference

README.md

@@ -17,12 +17,12 @@ Utility | Programmer(s)
 chgres_cube | George Gayno, Jeff Beck, Larissa Reames
 emcsfc_ice_blend | George Gayno
 emcsfc_snow2mdl | George Gayno
-fvcom_tools | David Wright, University of Michigan
-global_cycle | George Gayno, Shrinivas Moorthi
-grid_tools | R. J. Purser (regional_esg_grid), Tom Black/Ben Blake (shave.fd), Gerard Ketefian (global_equiv_resol), GFDL programmer (topo filtering code).
+fvcom_tools | David Wright, University of Michigan, Ming Hu, GSD/AMB
+global_cycle | George Gayno, Shrinivas Moorthi, Mark Iredell, Xu Li, Hang Lei
+grid_tools | R. J. Purser (regional_esg_grid), Tom Black/Ben Blake (shave.fd), Gerard Ketefian (global_equiv_resol), Tsukasa Fujita, JMA (pmat2), GFDL programmer (topo filtering code).
 orog_mask_tools | Ning Wang, Jordan Alpert, Shan Sun and Ning Wang
 sfc_climo_gen | George Gayno
-vcoord_gen | Fanglin Yang
+vcoord_gen | Fanglin Yang, Mark Iredell
 
 UFS_UTILS Code managers: George Gayno, Kyle Gerheiser
 

sorc/chgres_cube.fd/docs/user_guide.md

@@ -2,18 +2,18 @@
 
 # Introduction
 
-The chgres_cube program creates initial condition files to “coldstart”
+The program chgres.F90 creates initial condition files to “coldstart”
 the forecast model. The initial conditions are created from either
 Global Forecast System (GFS) gridded binary version 2 (GRIB2), NOAA
 Environmental Modeling System Input/Output (NEMSIO) data, or Network
 Common Data Form (NetCDF) data.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
-
-This user guide is part of the <a href="../index.html">UFS_UTILS
+This document is part of the <a href="../index.html">UFS_UTILS
 documentation</a>.
 
+The chgres_cube program is part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
+
 ## Where to find GFS GRIB2, NEMSIO and NetCDF data
 
 ### GRIB2

sorc/emcsfc_ice_blend.fd/docs/user_guide.md

@@ -3,15 +3,16 @@
 
 # Introduction
 
-Blends National Ice Center sea ice cover and EMC sea ice concentration
-data to create a global sea ice analysis used to update the GFS once
-per day.
+The emcsfc_ice_blend.f90 program blends National Ice Center sea ice
+cover and EMC sea ice concentration data to create a global sea ice
+analysis used to update the GFS once per day.
 
-This is part of the [NCEPLIBS
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
+
+The emcsfc_ice_blend program is part of the [NCEPLIBS
 UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
 
-The emcsfc_ice_blend code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/emcsfc_ice_blend.fd.
+
 

sorc/emcsfc_snow2mdl.fd/docs/user_guide.md

@@ -3,15 +3,14 @@
 
 # Introduction
 
-Blends National Ice Center snow cover and Air Force snow depth data to
-create a global depth analysis used to update the GFS snow field once
-per day.
+The emcsfc_snow2mdl program (driver.F90) blends National Ice Center
+snow cover and Air Force snow depth data to create a global depth
+analysis used to update the GFS snow field once per day.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
+The emcsfc_snow2mdl program is part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-The emcsfc_snow2mdl code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/emcsfc_snow2mdl.fd.
 

sorc/emcsfc_snow2mdl.fd/driver.F90

@@ -6,20 +6,6 @@
 !! or global gfs gaussian grid using nesdis/ims snow cover, autosnow snow
 !! cover and/or afwa depth data.
 !!      
-!! Program History Log
-!! -  2005-dec-16  gayno     initial version
-!! -  2007-nov-30  gayno     added processing of nam b-grids.
-!!                          improved thinning for gfs grids.
-!! -  2008-feb-01  gayno     added option to use autosnow data
-!!                          in southern hemisphere.
-!! -  2014-feb-14  gayno     read grib 1 or grib2 version of nesdis/ims
-!!                          data
-!! -  2014-sep-30  gayno     read grib 1 or grib2 version of model
-!!                          lat, lon and mask files.  convert
-!!                          nh weekly snow climatology to grib 2.
-!!                          option to output model depth and cover 
-!!                          analysis in grib2.
-!!
 !! The ims snow cover product is now produced by the national
 !! ice center, not nesdis.  however, in this code, references
 !! to ims still use the "nesdis" identifier.
@@ -139,6 +125,20 @@
 !!      defined threshold, the depth is set to 0,
 !!      regardless of the afwa depth value.
 !!
+!! Program History Log
+!! -  2005-dec-16  gayno     initial version
+!! -  2007-nov-30  gayno     added processing of nam b-grids.
+!!                          improved thinning for gfs grids.
+!! -  2008-feb-01  gayno     added option to use autosnow data
+!!                          in southern hemisphere.
+!! -  2014-feb-14  gayno     read grib 1 or grib2 version of nesdis/ims
+!!                          data
+!! -  2014-sep-30  gayno     read grib 1 or grib2 version of model
+!!                          lat, lon and mask files.  convert
+!!                          nh weekly snow climatology to grib 2.
+!!                          option to output model depth and cover 
+!!                          analysis in grib2.
+!!
 !! @return 0 for success, error code otherwise.      
 !! @author gayno @date 2005-dec-16
  program driver

sorc/fvcom_tools.fd/docs/user_guide.md

@@ -3,16 +3,16 @@
 
 # Introduction
 
-Replaces lake surface and lake ice temperature along with aerial ice
-concentration generated from the Great Lakes Operational Forecast
-System (GLOFS) in an FV3 surface restart file. See [fvcom
-documentation](@ref fvcom_readme).
+The process_FVCOM.f90 program replaces lake surface and lake ice
+temperature along with aerial ice concentration generated from the
+Great Lakes Operational Forecast System (GLOFS) in an FV3 surface
+restart file. See [fvcom documentation](@ref fvcom_readme).
 
-This is part of the [NCEPLIBS
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
+
+The fvcom_tools program is part of the [NCEPLIBS
 UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
 
-The fvcom_tools code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/fvcom_tools.fd.
 

sorc/global_cycle.fd/docs/user_guide.md

@@ -3,16 +3,13 @@
 
 # Introduction
 
-Updates the GFS surface conditions using external snow and sea ice
-analyses. Updates monthly climatological fields such as plant
-greenness fraction and albedo. Runs as part of the GFS and GDAS
-cycles.
+The program cycle.f90 updates the GFS surface conditions using
+external snow and sea ice analyses. It updates monthly climatological
+fields such as plant greenness fraction and albedo. It runs as part of
+the GFS and GDAS cycles.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
-
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
-
-The global_cycle code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/global_cycle.fd.
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
 
+The global_cycle program is part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.

sorc/grid_tools.fd/docs/user_guide.md

@@ -3,15 +3,19 @@
 
 # Introduction
 
-Utilities to filter topography, to create regional extended Schmidt
-gnomonic grids, and to compute the equivalent global resolution of a
-regional grid.
+The grid_tools include:
+* filter_topo.F90 - filter topography
+* global_equiv_resol.f90 - compute the equivalent global resolution of
+  a regional grid
+* regional_esg_grid.f90 - create regional extended Schmidt gnomonic
+  grids
+* shave_nc.F90 - shave down domains of FV3 files
 
-This is part of the [NCEPLIBS
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
+
+The grid_tools programs are part of the [NCEPLIBS
 UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
 
-The grid_tools code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/grid_tools.fd.
 

sorc/grid_tools.fd/regional_esg_grid.fd/pmat2.f90

@@ -640,7 +640,6 @@ end subroutine LDLTB
 !! @param[in] mah1 semi-bandwidth of matrix A
 !! @param[inout] a input lower (left) part of symmetric A; output its factors
 !! encoded as [L-I]+[D**-1]
-!! @param[inout] a input lower (left) part of symmetric A; output its factors.
 !! @author R. J. Purser, Tsukasa Fujita (JMA) @date 1999
 subroutine DLDLTB(m,mah1,a) ! Real(dp) version of                   [LDLTB]
 use pietc, only: u0,u1
@@ -720,17 +719,14 @@ end subroutine DUDLB
 !!  lower triangular elements of [A] by [D**-1]*[L]*[D], the upper by [U],
 !!  replace matrix [B] by [D**-1]*[B].
 !!
-!! @param[inout] a input as band matrix, output as lower and upper triangulars with 1s
-!! implicitly assumed to lie on the main diagonal. The product of these
-!! triangular matrices is [D**-1]*[A], where [D] is a diagonal matrix.
-!! @param[inout] b in as band matrix, out as same but premultiplied by diagonal [D**-1]
 !! @param[in] m Number of rows of A and B
 !! @param[in] mah1 number of subdiagonals of A
 !! @param[in] mah2 number of superdiagonals of A
 !! @param[in] mbh1 number of subdiagonals of B
 !! @param[in] mbh2 number of superdiagonals of B
-!! @param[inout] a Input single precision band matrix A; output factors encoded
-!! as [D**-1 * L * D]+[U-I]
+!! @param[inout] a input as band matrix, output as lower and upper triangulars with 1s
+!! implicitly assumed to lie on the main diagonal. The product of these
+!! triangular matrices is [D**-1]*[A], where [D] is a diagonal matrix.
 !! @param[inout] b Input single precision band matrix B; output [D**-1 B]
 !! @author R. J. Purser, Tsukasa Fujita (JMA) @date 1996
 subroutine L1UBB(m,mah1,mah2,mbh1,mbh2,a,b)!                           [L1UBB] 

sorc/orog_mask_tools.fd/docs/user_guide.md

@@ -3,14 +3,15 @@
 
 # Introduction
 
-Utilities to create land mask, terrain and gravity wave drag fields;
-set lake fraction and depth; creates an inland land mask.
+The orog_mask_tools include:
+* inland.F90 - create an inland land mask.
+* lakefrac.F90 - set lake fraction and depth.
+* mtnlm7_oclsm.f - terrain maker for global spectral model.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
+The orog_mask_tools programs are part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-The orog_mask_tools code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/orog_mask_tools.fd.
 

sorc/orog_mask_tools.fd/orog.fd/mtnlm7_oclsm.f

@@ -1,23 +1,25 @@
 C> @file
-C> TERRAIN MAKER FOR GLOBAL SPECTRAL MODEL
-C> @author IREDELL @date 92-04-16
+C> Terrain maker for global spectral model.
+C> @author Mark Iredell @date 92-04-16
 
-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
-C>   AND FILTER PARAMETERS ARE READ BY THIS PROGRAM AS INPUT.
-C>   THE 7 FILES PRODUCED ARE RESPECTIVELY:
-C>     1) SEA-LAND MASK ON MODEL PHYSICS GRID
-C>     2) GRIDDED OROGRAPHY ON MODEL PHYSICS GRID
-C>     3) MOUNTAIN STD DEV ON MODEL PHYSICS GRID
-C>     4) SPECTRAL OROGRAPHY IN SPECTRAL DOMAIN
-C>     5) UNFILTERED GRIDDED OROGRAPHY ON MODEL PHYSICS GRID
-C>     6) GRIB SEA-LAND MASK ON MODEL PHYSICS GRID
-C>     7) GRIB GRIDDED OROGRAPHY ON MODEL PHYSICS GRID
-C>   THE OROGRAPHY IS ONLY FILTERED FOR WAVENUMBERS GREATER THAN NF0.
-C>   FOR WAVENUMBERS N BETWEEN NF0 AND NF1, THE OROGRAPHY IS FILTERED
-C>   BY THE FACTOR 1-((N-NF0)/(NF1-NF0))**2.  THE FILTERED OROGRAPHY
-C>   WILL NOT HAVE INFORMATION BEYOND WAVENUMBER NF1.
+C> This program creates 7 terrain-related files computed from the navy
+C> 10-minute terrain dataset. The model physics grid parameters and
+C> spectral truncation and filter parameters are read by this program as
+C> input.
+C>      
+C> The 7 files produced are:
+C> 1. sea-land mask on model physics grid
+C> 2. gridded orography on model physics grid
+C> 3. mountain std dev on model physics grid
+C> 4. spectral orography in spectral domain
+C> 5. unfiltered gridded orography on model physics grid
+C> 6. grib sea-land mask on model physics grid
+C> 7. grib gridded orography on model physics grid
+C>
+C> The orography is only filtered for wavenumbers greater than nf0. For
+C> wavenumbers n between nf0 and nf1, the orography is filtered by the
+C> factor 1-((n-nf0)/(nf1-nf0))**2. The filtered orography will not have
+C> information beyond wavenumber nf1.
 C>
 C> PROGRAM HISTORY LOG:
 C> -  92-04-16  IREDELL
@@ -71,8 +73,6 @@
 C>  -   SPTEZ      - SPHERICAL TRANSFORM
 C>  -   GBYTES     - UNPACK BITS
 C>
-C>   REMARKS: FORTRAN 9X EXTENSIONS ARE USED.
-C>
 C> @return 0 for success, error code otherwise.
       include 'netcdf.inc'
       logical fexist, opened

sorc/sfc_climo_gen.fd/docs/user_guide.md

@@ -3,14 +3,13 @@
 
 # Introduction
 
-Creates surface climatological fields, such as vegetation type and
-albedo, for an FV3 grid.
+The sfc_climo_gen program driver.F90 creates surface climatological
+fields, such as vegetation type and albedo, for an FV3 grid.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
+The orog_mask_tools programs are part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-The sfc_climo_gen code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/sfc_climo_gen.fd.
 

sorc/vcoord_gen.fd/docs/user_guide.md

@@ -3,16 +3,15 @@
 
 # Introduction
 
-Generates hybrid coordinate parameters from fields such as surface
-pressure, model top and the number of vertical levels. Outputs the
-'ak' and 'bk' parameters used by the forecast model to define the
-hybrid levels.
+The vcoord_gen program driver.f90 generates hybrid coordinate
+parameters from fields such as surface pressure, model top and the
+number of vertical levels. Outputs the 'ak' and 'bk' parameters used
+by the forecast model to define the hybrid levels.
 
-This is part of the [NCEPLIBS
-UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
+This document is part of the <a href="../index.html">UFS_UTILS
+documentation</a>.
 
-This is part of the <a href="../index.html">UFS_UTILS documentation</a>.
+The vcoord_gen programs are part of the [NCEPLIBS
+UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) project.
 
-The vcoord_gen can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/vcoord_gen.fd.
 

sorc/vcoord_gen.fd/driver.f90

@@ -2,7 +2,11 @@
 !! @brief Driver for vcoord_gen.
 !! @author Mark Iredell @date 2008-08-01
 
-!> Driver for vcoord_gen.
+!> This program generates hybrid coordinate
+!! parameters from fields such as surface pressure, model top and the
+!! number of vertical levels. Outputs the 'ak' and 'bk' parameters
+!! used by the forecast model to define the hybrid levels.
+!!
 !! @return 0 for success, error code otherwise.
 !! @author Mark Iredell @date 2008-08-01
 program driver