clearing doxygen warnings for sfc_climo_gen

docs/Doxyfile.in

@@ -733,7 +733,7 @@ WARN_LOGFILE           =
 
 # WARN_AS_ERROR causes warnings to be treated as errors.
 
-WARN_AS_ERROR = NO
+WARN_AS_ERROR = YES
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files

docs/user_guide.md

@@ -29,8 +29,7 @@ https://github.com/NOAA-EMC/UFS_UTILS.
 - <a href="fvcom_tools/index.html">fvcom_tools</a> - 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).
+  in an FV3 surface restart file. 
 
 - <a href="global_cycle/index.html">global_cycle</a> -
   Updates the GFS surface conditions using external snow and sea ice

sorc/sfc_climo_gen.fd/docs/Doxyfile.in

@@ -733,7 +733,7 @@ WARN_LOGFILE           =
 
 # WARN_AS_ERROR causes warnings to be treated as errors.
 
-WARN_AS_ERROR = NO
+WARN_AS_ERROR = YES
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files

sorc/sfc_climo_gen.fd/driver.F90

@@ -1,6 +1,9 @@
 !> @file
-!!
-!! Reads static surface data on a global lat/lon grid,
+!! @brief Interpolates static surface data from lat/lon grid,
+!! to FV3 model grid.
+!! @author George Gayno
+
+!> Reads static surface data on a global lat/lon grid,
 !! interpolates the data to the fv3 model grid, and outputs the
 !! result in netcdf format.
 !!
@@ -16,6 +19,8 @@
 !!
 !! Outputs surface data on the model tiles in netcdf format.
 !!
+!! @return 0 for success, error code otherwise.
+!! @author George Gayno
  program driver  
 
  use model_grid

sorc/sfc_climo_gen.fd/interp.F90

@@ -1,13 +1,15 @@
 !> @file
 !! @brief Read the input source data and interpolate it to the
 !! model grid.
+!! @author George Gayno @date 2018
+
+!> Read the input source data and interpolate it to the
+!! model grid.
 !!
-!! @author gayno @date 2018
-!!
-!! @param[in] input_flle filename of input source data.
 !! @param[in] localpet this mpi task
 !! @param[in] method interpolation method.defined where mask=1
-!!
+!! @param[in] input_file filename of input source data.
+!! @author George Gayno @date 2018
  subroutine interp(localpet, method, input_file)
 
  use esmf
@@ -259,16 +261,16 @@ subroutine interp(localpet, method, input_file)
 
  end subroutine interp
 
-!> Ensure consistent fields at land ice points
+!> Ensure consistent fields at land ice points.
 !! Land ice is vegetation type 15 (variable landice).
+!! output is Model field.
+!!
+!! @param[in] field Model field before adjustments for land ice.
+!! @param[in] vegt Vegetation type on the model tile.
+!! @param[inout] idim i dimension of model tile.
+!! @param[inout] jdim j dimension of model tile.
+!! @param[in] field_ch Field name.
 !! @author George Gayno NCEP/EMC
-!! Usage: call adjust_for_landice(field, vegt, idim, jdim, field_ch)
-!! output is Model field
-!! @param field         - Model field before adjustments for land ice.
-!! @param field_ch      - Field name.
-!! @param i/jdim        - i/j dimension of model tile.
-!! @param vegt          - Vegetation type on the model tile.
-
  subroutine adjust_for_landice(field, vegt, idim, jdim, field_ch)
 
  use esmf

sorc/sfc_climo_gen.fd/model_grid.F90

@@ -1,34 +1,12 @@
 !> @file
-!! Defines the model grid.
-!! @author gayno @date 2018
-!!
-!! ### Public Subroutines:
-!! - define_model_grid            Defines esmf grid object for the
-!!                              model grid.
-!! - model_grid_cleanup           Free up memory used in this module.
-!!
-!! ### Public variables:
+!! @brief Defines the model grid.
+!! @author George Gayno @date 2018
+
+!> This module defines the model grid.
 !!
 !! Variables named with 'mdl' refer to the model grid.
 !!
-!! - data_field_mdl               ESMF field object that holds the
-!!                              data interpolated to model grid.
-!! - grid_mdl                     ESMF grid object for the model grid.
-!! - grid_tiles                   Array of model grid tile names.
-!! - i/j_mdl                      i/j dimensions of model tile.
-!! - latitude_field_mdl           ESMF field object that holds the
-!!                              model grid latitude
-!! - longitude_field_mdl          ESMF field object that holds the
-!!                              model grid longitude
-!! - mdl_field_mdl                ESMF field object that holds the
-!!                              model land mask.
-!! - missing                      Value assigned to undefined points
-!!                              (i.e., ocean points for a land
-!!                              field).
-!! - num_tiles                    Total number of model grid tiles.
-!! - vegt_field_mdl               ESMF field object that holds the
-!!                              vegetation type on the model grid.
-!! 
+!! @author George Gayno @date 2018
  module model_grid
 
  use esmf
@@ -37,31 +15,41 @@ module model_grid
 
  private
 
- character(len=5), allocatable, public  :: grid_tiles(:)
+ character(len=5), allocatable, public  :: grid_tiles(:) !< Array of model grid tile names.
 
- integer, public               :: i_mdl, j_mdl, ij_mdl, num_tiles
+ integer, public               :: i_mdl !< i dimension of model tile.
+ integer, public               :: j_mdl !< j dimension of model tile.
+ integer, public               :: ij_mdl !< ???
+ integer, public               :: num_tiles !< Total number of model grid tiles.
 
- real(kind=4), public          :: missing = -999.
+ real(kind=4), public          :: missing = -999. !<Value assigned to undefined points
+                                                  !! (i.e., ocean points for a land field).
 
- type(esmf_grid),  public      :: grid_mdl
- type(esmf_field), public      :: data_field_mdl, mask_field_mdl
- type(esmf_field), public      :: latitude_field_mdl, longitude_field_mdl
- type(esmf_field), public      :: vegt_field_mdl
+ type(esmf_grid),  public      :: grid_mdl !< ESMF grid object for the model grid.
+ type(esmf_field), public      :: data_field_mdl !< ESMF field object that holds the
+                                                 !! data interpolated to model grid.
+ type(esmf_field), public      :: mask_field_mdl !< ESMF field object that holds the
+                                                 !! model land mask.
+ type(esmf_field), public      :: latitude_field_mdl !< ESMF field object that holds the
+                                                     !! model grid latitude.
+ type(esmf_field), public      :: longitude_field_mdl !< ESMF field object that holds the
+                                                      !! model grid longitude.
+ type(esmf_field), public      :: vegt_field_mdl !< ESMF field object that holds the
+                                                 !! vegetation type on the model grid.
 
  public                        :: define_model_grid
  public                        :: model_grid_cleanup
 
  contains
 
-!> define model grid
-!! @author gayno @date 2018
+!> Define model grid.
 !!
 !! Define the model grid from the mosaic and orography
-!! files.  Create the ESMF grid object for the model grid.
+!! files. Create the ESMF grid object for the model grid.
 !!
 !! @param[in] localpet this mpi task      
 !! @param[in] npets total number of mpi tasks      
-!!
+!! @author George Gayno @date 2018
  subroutine define_model_grid(localpet, npets)
 
  use esmf
@@ -282,7 +270,6 @@ subroutine define_model_grid(localpet, npets)
  end subroutine define_model_grid
 
 !> Get model information
-!! @author gayno @date 2018
 !!
 !! Read model land/sea mask and lat/lon from the orography file.
 !!
@@ -292,7 +279,7 @@ end subroutine define_model_grid
 !! @param[out] lon2d longitude
 !! @param[in] idim i dimension of the model tile
 !! @param[in] jdim j dimension of the model tile
-!!
+!! @author George Gayno @date 2018
  subroutine get_model_info(orog_file, mask, lat2d, lon2d, idim, jdim)
 
  use esmf
@@ -392,11 +379,11 @@ subroutine get_model_info(orog_file, mask, lat2d, lon2d, idim, jdim)
 
  end subroutine get_model_info
 
-!> model grid cleanup
-!! @author gayno @date 2018
+!> Model grid cleanup.
 !!
 !! Free up memory associated with this module.
 !!
+!! @author George Gayno @date 2018
  subroutine model_grid_cleanup
 
  implicit none

sorc/sfc_climo_gen.fd/output.f90

@@ -1,9 +1,8 @@
 !> @file
+!! @brief Output model data for a single tile and a single record.
+!! @author George Gayno @date 2018
 
-!> output
-!! @author gayno @date 2018
-!!
-!! Output model data for a single tile and a single
+!> Output model data for a single tile and a single
 !! record in netcdf format.
 !!
 !! @param[in] data_one_tile Data to be output (single tile).
@@ -15,7 +14,7 @@
 !! @param[in] record Record number to be output.
 !! @param[in] tile Tile number.
 !! @param[in] time Time period to be output.
-!!
+!! @author George Gayno @date 2018
  subroutine output(data_one_tile, lat_one_tile, lon_one_tile, i_mdl, j_mdl, &
                    tile, record, time, field_idx)
 

sorc/sfc_climo_gen.fd/program_setup.f90

@@ -1,13 +1,8 @@
 !> @file
+!! @brief Program setup.
+!! @author George Gayno @date 2018
 
-!> program setup
-!! @author gayno @date 2018
-!!
-!! Set up program execution
-!!
-!! Public Subroutines:
-!! -------------------
-!! - read_setup_namelist          Reads configuration namelist
+!> Set up program execution
 !!
 !! Public variables:
 !! -----------------
@@ -19,76 +14,44 @@
 !! However, vegetation type must always be processed as it defines
 !! landice points.
 !!
-!! - halo                         Number of row/cols defining the lateral
-!!                              boundary halo.  Used for regionanl
-!!                              nests.
-!! - input_facsf_file             File containing input fractional
-!!                              coverage data for strong zenith angle
-!!                              dependent albedo.
-!! - input_vegetation_greenness_  File containing input vegetation
-!! - file                         greenness data.
-!! - input_leaf_area_index_file   File containing input leaf area index   
-!!                              data.
-!! - input_maximum_snow_albedo_file   File containing input maximum snow
-!!                          albedo data.
-!! - input_snowfree_albedo_file   File containing input snow-free 
-!!                              albedo data.
-!! - input_soil_type_file         File containing input soil type data.
-!! - input_slope_type_file        File containing input slope type data.
-!! - input_substrate_temperature_file File containing input soil substrate
-!!                          temperature data.
-!! - input_vegetation_type_file   File containing input vegetation type data.
-!! - leaf_area_index_method       Interpolation method for leaf area index.
-!!                              Conservative or bilinear (default).
-!! - maximum snow albedo_method   Interpolation method for max snow albedo.
-!!                              Conservative or bilinear (default).
-!! - mosaic_file_mdl              Model grid mosaic file
-!! - orog_dir_mdl                 Directory containing the model grid
-!!                              orography files.
-!! - orog_files_mdl               Model grid orography filenames.
-!! - snowfree_albedo_method       Interpolation method for snowfree albedo.
-!!                              Conservative or bilinear (default).
-!! - vegetation_greenness_        Interpolation method for vegetation 
-!! - method                       greenness.  Conservative or bilinear.
-!!                              Default is bilinear.
-!!
+!! @author George Gayno @date 2018
  module program_setup
 
  implicit none
 
  private
 
- character(len=500), public   :: input_leaf_area_index_file = "NULL"
- character(len=500), public   :: input_facsf_file = "NULL"
- character(len=500), public   :: input_substrate_temperature_file = "NULL"
- character(len=500), public   :: input_maximum_snow_albedo_file = "NULL"
- character(len=500), public   :: input_snowfree_albedo_file = "NULL"
- character(len=500), public   :: input_slope_type_file = "NULL"
- character(len=500), public   :: input_soil_type_file = "NULL"
- character(len=500), public   :: input_vegetation_type_file = "NULL"
- character(len=500), public   :: input_vegetation_greenness_file = "NULL"
- character(len=500), public   :: mosaic_file_mdl = "NULL"
- character(len=500), public   :: orog_dir_mdl = "NULL"
- character(len=500), public   :: orog_files_mdl(6) = "NULL"
-
- character(len=50), public    :: leaf_area_index_method='bilinear'
- character(len=50), public    :: maximum_snow_albedo_method='bilinear'
- character(len=50), public    :: snowfree_albedo_method='bilinear'
- character(len=50), public    :: vegetation_greenness_method='bilinear'
-
- integer, public              :: halo = 0
+ character(len=500), public   :: input_leaf_area_index_file = "NULL" !< File containing input leaf area index data.
+ character(len=500), public   :: input_facsf_file = "NULL" !< File containing input fractional
+                                                           !! coverage data for strong zenith angle
+                                                           !! dependent albedo.
+ character(len=500), public   :: input_substrate_temperature_file = "NULL" !< File containing input soil substrate temperature data.
+ character(len=500), public   :: input_maximum_snow_albedo_file = "NULL" !< File containing input maximum snow albedo data.
+ character(len=500), public   :: input_snowfree_albedo_file = "NULL" !< File containing input snow-free albedo data.
+ character(len=500), public   :: input_slope_type_file = "NULL" !< File containing input slope type data.
+ character(len=500), public   :: input_soil_type_file = "NULL" !< File containing input soil type data.
+ character(len=500), public   :: input_vegetation_type_file = "NULL" !< File containing input vegetation type data.
+ character(len=500), public   :: input_vegetation_greenness_file = "NULL" !< File containing input vegetation greenness data.
+ character(len=500), public   :: mosaic_file_mdl = "NULL" !< Model grid mosaic file.
+ character(len=500), public   :: orog_dir_mdl = "NULL" !< Directory containing the model grid orography files.
+ character(len=500), public   :: orog_files_mdl(6) = "NULL" !< Model grid orography filenames.
+
+ character(len=50), public    :: leaf_area_index_method='bilinear' !< Interpolation method for leaf area index. Conservative or bilinear (default).
+ character(len=50), public    :: maximum_snow_albedo_method='bilinear' !< Interpolation method for max snow albedo. Conservative or bilinear (default).
+ character(len=50), public    :: snowfree_albedo_method='bilinear' !< Interpolation method for snowfree albedo. Conservative or bilinear (default).
+ character(len=50), public    :: vegetation_greenness_method='bilinear' !< Interpolation method for vegetation greenness. Conservative or bilinear (default).
+
+ integer, public              :: halo = 0 !< Number of row/cols defining the lateral
+                                          !! boundary halo. Used for regional nests.
 
  public :: read_setup_namelist
 
  contains
 
-!> read setup namelist
-!! @author gayno @date 2018
-!!
-!! Read program setup namelist
+!> Read program setup namelist
 !!
 !! @param[in] localpet mpi task number
-!!
+!! @author George Gayno @date 2018
  subroutine read_setup_namelist(localpet)
 
  use mpi

sorc/sfc_climo_gen.fd/search.f90

@@ -1,22 +1,25 @@
 !> @file
-!! @author gayno @date 2018
-!
+!! @brief Replace undefined values on the model grid with a valid
+!! value at a nearby neighbor.
+!! @author George Gayno @date 2018
+
 !> Replace undefined values on the model grid with a valid
-!! value at a nearby neighbor.  Undefined values are typically
+!! value at a nearby neighbor. Undefined values are typically
 !! associated with isolated islands where there is no source data.
 !! Routine searches a neighborhood with a radius of 100 grid points.
-!! If no valid value is found, a default value is used.  This
-!! routine works for one tile of a cubed sphere grid.  It does
-!! not consider valid values at adjacent faces.  That is a future
+!! If no valid value is found, a default value is used. This
+!! routine works for one tile of a cubed sphere grid. It does
+!! not consider valid values at adjacent faces. That is a future
 !! upgrade.
 !!
-!! @param[in] idim/jdim i/j dimensions of tile
-!! @param[in] tile tile number
-!! @param[in] mask field bitmap.  field defined where mask=1
-!! @param[in] field_name field name
 !! @param[inout] field - input: field before missing values are replaced
 !!                     - output: field after missing values are replaced
-!!
+!! @param[in] mask field bitmap. Field defined where mask=1
+!! @param[inout] idim i dimension of tile
+!! @param[inout] jdim j dimension of tile
+!! @param[in] tile tile number
+!! @param[in] field_name field name
+!! @author George Gayno @date 2018
  subroutine search (field, mask, idim, jdim, tile, field_name)
 
  use mpi