From c1a1d297f37d1eb5151c50fa1143174f20982a75 Mon Sep 17 00:00:00 2001
From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com>
Date: Thu, 25 Feb 2021 08:26:45 -0700
Subject: [PATCH] for chgres_cube - soil parameter references in
 program_setup.f90, turned on doxygen documentation for private functions
 (#352)

* turned on documentation of private functions

* turned on documentation of private functions

* documentation cleanup, references for soil params

* fixed links

* fixed links

* undoing

* reapplied doc changes
---
 docs/Doxyfile.in                      |  4 ++--
 sorc/chgres_cube.fd/program_setup.F90 | 33 +++++++++++++++++++++++----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index 20e6fbc7e..d596f9b16 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -402,13 +402,13 @@ EXTRACT_ALL            = NO
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
 # scope will be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PACKAGE        = NO
+EXTRACT_PACKAGE        = YES
 
 # If the EXTRACT_STATIC tag is set to YES all static members of a file will be
 # included in the documentation.
diff --git a/sorc/chgres_cube.fd/program_setup.F90 b/sorc/chgres_cube.fd/program_setup.F90
index 4ec07d3e9..49964b44e 100644
--- a/sorc/chgres_cube.fd/program_setup.F90
+++ b/sorc/chgres_cube.fd/program_setup.F90
@@ -1,7 +1,8 @@
 !> @file
-!! @brief Set up program execution
+!! @brief Set up program execution.
 !!
-!! Set up program execution
+!! This module contains code to read the setup namelist file, handle
+!! the varmap file for GRIB2 data, and calculate the soil parameters.
 !!
 !! @author George Gayno NCEP/EMC
  module program_setup
@@ -144,7 +145,8 @@ module program_setup
 
 !> Reads program configuration namelist.
 !!
-!! @param filename the name of the configuration file (defaults to ./fort.41).
+!! @param filename the name of the configuration file (defaults to
+!! ./fort.41).
 !! @author George Gayno NCEP/EMC
  subroutine read_setup_namelist(filename)
  implicit none
@@ -443,6 +445,27 @@ end subroutine get_var_cond
 !> Driver routine to compute soil parameters for each
 !! soil type. Works for Zobler and STATSGO soil categories.
 !!
+!! The calculations are those used in the Noah Land Surface Model. For
+!! more information see <a
+!! href="https://doi.org/10.1029/2002JD003296">Implementation of Noah
+!! land surface model advances in the National Centers for
+!! Environmental Prediction operational mesoscale Eta model</a>.
+!!
+!! For more details about the soil parameters/properties see <a
+!! href="https://journals.ametsoc.org/view/journals/mwre/129/4/1520-0493_2001_129_0569_caalsh_2.0.co_2.xml">Coupling
+!! an Advanced Land Surface–Hydrology Model with the Penn State–NCAR
+!! MM5 Modeling System. Part I: Model Implementation and
+!! Sensitivity</a>.
+!!
+!! The original source for soil properties is here:
+!!
+!! Cosby, B. J., G. M. Hornberger, R. B. Clapp, and T. R. Ginn, 1984:
+!! <a
+!! href="https://agupubs.onlinelibrary.wiley.com/doi/10.1029/WR020i006p00682">A
+!! statistical exploration of the relationships of soil moisture
+!! characteristics to the physical properties of soils</a>. Water
+!! Resour. Res.,20, 682–690.
+!!
 !! @param [in] localpet  ESMF local persistent execution thread
 !! @author George Gayno NCEP/EMC
  subroutine calc_soil_params_driver(localpet)
@@ -588,8 +611,8 @@ subroutine calc_soil_params_driver(localpet)
 
  end subroutine calc_soil_params_driver
 
-!> Compute soil parameters.  Will be used to rescale soil moisture
-!! differences in soil type between the input grid and target
+!> Compute soil parameters. These will be used to rescale soil
+!! moisture differences in soil type between the input grid and target
 !! model grid.
 !!
 !! @param [in] num_soil_cats  number of soil type categories