[develop]: Update most remaining documentation files

docs/Doxyfile.in

@@ -93,14 +93,6 @@ ALLOW_UNICODE_NAMES    = NO
 
 OUTPUT_LANGUAGE        = English
 
-# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all
-# documentation generated by doxygen is written. Doxygen will use this
-# information to generate all generated output in the proper direction.
-# Possible values are: None, LTR, RTL and Context.
-# The default value is: None.
-
-OUTPUT_TEXT_DIRECTION  = None
-
 # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
 # descriptions after the members that are listed in the file and class
 # documentation (similar to Javadoc). Set to NO to disable this.
@@ -1111,44 +1103,6 @@ USE_HTAGS              = NO
 
 VERBATIM_HEADERS       = YES
 
-# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
-# clang parser (see:
-# http://clang.llvm.org/) for more accurate parsing at the cost of reduced
-# performance. This can be particularly helpful with template rich C++ code for
-# which doxygen's built-in parser lacks the necessary type information.
-# Note: The availability of this option depends on whether or not doxygen was
-# generated with the -Duse_libclang=ON option for CMake.
-# The default value is: NO.
-
-CLANG_ASSISTED_PARSING = NO
-
-# If clang assisted parsing is enabled and the CLANG_ADD_INC_PATHS tag is set to
-# YES then doxygen will add the directory of each input to the include path.
-# The default value is: YES.
-
-CLANG_ADD_INC_PATHS    = YES
-
-# If clang assisted parsing is enabled you can provide the compiler with command
-# line options that you would normally use when invoking the compiler. Note that
-# the include paths will already be set by doxygen for the files and directories
-# specified with INPUT and INCLUDE_PATH.
-# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
-
-CLANG_OPTIONS          =
-
-# If clang assisted parsing is enabled you can provide the clang parser with the
-# path to the directory containing a file called compile_commands.json. This
-# file is the compilation database (see:
-# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the
-# options used when the source files were built. This is equivalent to
-# specifying the -p option to a clang tool, such as clang-check. These options
-# will then be passed to the parser. Any options specified with CLANG_OPTIONS
-# will be added as well.
-# Note: The availability of this option depends on whether or not doxygen was
-# generated with the -Duse_libclang=ON option for CMake.
-
-CLANG_DATABASE_PATH    =
-
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
@@ -1590,17 +1544,6 @@ HTML_FORMULA_FORMAT    = png
 
 FORMULA_FONTSIZE       = 10
 
-# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
 # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands
 # to create new LaTeX commands to be used in formulas as building blocks. See
 # the section "Including formulas" for details.
@@ -1809,7 +1752,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just
@@ -1904,16 +1847,6 @@ LATEX_BATCHMODE        = NO
 
 LATEX_HIDE_INDICES     = NO
 
-# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
-# code with syntax highlighting in the LaTeX output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_SOURCE_CODE      = NO
-
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
 # https://en.wikipedia.org/wiki/BibTeX and \cite for more info.
@@ -1994,16 +1927,6 @@ RTF_STYLESHEET_FILE    =
 
 RTF_EXTENSIONS_FILE    =
 
-# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
-# with syntax highlighting in the RTF output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_RTF is set to YES.
-
-RTF_SOURCE_CODE        = NO
-
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -2100,15 +2023,6 @@ GENERATE_DOCBOOK       = NO
 
 DOCBOOK_OUTPUT         = docbook
 
-# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
-# program listings (including syntax highlighting and cross-referencing
-# information) to the DOCBOOK output. Note that enabling this will significantly
-# increase the size of the DOCBOOK output.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
-
-DOCBOOK_PROGRAMLISTING = NO
-
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -2287,15 +2201,6 @@ EXTERNAL_PAGES         = NO
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 
-# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram
-# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
-# NO turns the diagrams off. Note that this option also works with HAVE_DOT
-# disabled, but it is recommended to install and use dot, since it yields more
-# powerful graphs.
-# The default value is: YES.
-
-CLASS_DIAGRAMS         = YES
-
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.
@@ -2328,23 +2233,6 @@ HAVE_DOT               = NO
 
 DOT_NUM_THREADS        = 0
 
-# When you want a differently looking font in the dot files that doxygen
-# generates you can specify the font name using DOT_FONTNAME. You need to make
-# sure dot is able to find the font, which can be done by putting it in a
-# standard location or by setting the DOTFONTPATH environment variable or by
-# setting DOT_FONTPATH to the directory containing the font.
-# The default value is: Helvetica.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTNAME           = Helvetica
-
-# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
-# dot graphs.
-# Minimum value: 4, maximum value: 24, default value: 10.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTSIZE           = 10
-
 # By default doxygen will tell dot to use the default font as specified with
 # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
 # the path where dot can find it using this tag.
@@ -2581,18 +2469,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not seem
-# to support this out of the box.
-#
-# Warning: Depending on the platform used, enabling this option may lead to
-# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
-# read).
-# The default value is: NO.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_TRANSPARENT        = NO
-
 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
 # makes dot run faster, but since only newer versions of dot (>1.8.10) support

sorc/ncep_post.fd/CALHEL2.f

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

sorc/ncep_post.fd/CALHEL3.f

@@ -18,11 +18,13 @@
 !> @param[out] UST Estimated U Component (m/s) Of Storm motion.
 !> @param[out] VST Estimated V Component (m/s) Of Storm motion.
 !> @param[out] HELI Storm-relative heliciry (m**2/s**2).
-!> @var CANGLE Critical angle.
-!> @var USHR1 U Component (m/s) Of 0-1 km shear.
-!> @var VSHR1 V Component (m/s) Of 0-1 km shear.
-!> @var USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
-!> @var VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!>
+!> @note
+!> @li CANGLE Critical angle.
+!> @li USHR1 U Component (m/s) Of 0-1 km shear.
+!> @li VSHR1 V Component (m/s) Of 0-1 km shear.
+!> @li USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @li VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
 !>     
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -44,15 +46,6 @@
 !>   
 !> @author Michael Baldwin W/NP2 @date 1994-08-22
 !-----------------------------------------------------------------------
-!> @brief Subroutine that computes storm relative helicity.
-!
-!> @param[in] LLOW Lower bound CAPE>=100 and CINS>=-250.
-!> @param[in] LUPP Upper bound CAPE< 100  or CINS< -250; allows one to distinguish 0-3 km and 0-1 km values.
-!> @param[out] UST Estimated U Component (m/s) Of Storm motion.
-!> @param[out] VST Estimated V Component (m/s) Of Storm motion.
-!> @param[out] HELI Storm-relative heliciry (m**2/s**2).
-!-----------------------------------------------------------------------
-
       SUBROUTINE CALHEL3(LLOW,LUPP,UST,VST,HELI)
 
 !

sorc/ncep_post.fd/CALMICT.f

@@ -1,7 +1,7 @@
 !> @file
 !> @brief Subroutine that computes hydrometeors.
 !>
-!> This routin computes the mixing ratios of cloud water,
+!> This routine computes the mixing ratios of cloud water,
 !> cloud ice, rain, and snow. The code is based on subroutines
 !> GSMDRIVE and GSMCOLUMN in the NMM model.
 !>
@@ -21,6 +21,8 @@
 !> @param[out] DBZR Equivalent radar reflectivity factor from rain in dBZ.
 !> @param[out] DBZI Equivalent radar reflectivity factor from ice (all forms) in dBZ.
 !> @param[out] DBZC Equivalent radar reflectivity factor from parameterized convection in dBZ.
+!> @param[inout] NLICE1 Time-averaged number concentration of large ice. 
+!> @param[inout] NRAIN1 Number concentration of rain drops (m).
 !>
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -33,8 +35,35 @@
 !> 2021-09-02 | Bo Cui       | Decompose UPP in X direction          
 !>
 !> @author Yi Jin W/NP2 @date 2001-08-14
-      SUBROUTINE CALMICT_new(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL,     &
-                        QW1,QI1,QR1,QS1,DBZ1,DBZR1,DBZI1,DBZC1,NLICE1,NRAIN1)
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes hydrometeors.
+!>
+!> This routine computes the mixing ratios of cloud water,
+!> cloud ice, rain, and snow. The code is based on subroutines
+!> GSMDRIVE and GSMCOLUMN in the NMM model.
+!>
+!> @param[in] P1D Pressure (Pa).
+!> @param[in] T1D Temperature (K).
+!> @param[in] Q1D Specific humidity (kg/kg).
+!> @param[in] C1D Total condensate (CWM, kg/kg).
+!> @param[in] FI1D F_ice (fraction of condensate in form of ice).
+!> @param[in] FR1D F_rain (fraction of liquid water in form of rain).
+!> @param[in] FS1D F_RimeF ("Rime Factor", ratio of total ice growth to deposition growth).
+!> @param[in] CUREFL Radar reflectivity contribution from convection (mm**6/m**3).
+!> @param[inout] QW1 Cloud water mixing ratio (kg/kg).
+!> @param[inout] QI1 Cloud ice mixing ratio (kg/kg).
+!> @param[inout] QR1 Rain mixing ratio (kg/kg).
+!> @param[inout] QS1 "Snow" (precipitation ice) mixing ratio (kg/kg).
+!> @param[inout] DBZ1 Equivalent radar reflectivity factor in dBZ; i.e., 10*LOG10(Z).
+!> @param[inout] DBZR1 Equivalent radar reflectivity factor from rain in dBZ.
+!> @param[inout] DBZI1 Equivalent radar reflectivity factor from ice (all forms) in dBZ.
+!> @param[inout] DBZC1 Equivalent radar reflectivity factor from parameterized convection in dBZ.
+!> @param[inout] NLICE1 Time-averaged number concentration of large ice. 
+!> @param[inout] NRAIN1 Number concentration of rain drops (m).
+!>
+!-----------------------------------------------------------------------
+      SUBROUTINE CALMICT_new(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL, &
+                  QW1,QI1,QR1,QS1,DBZ1,DBZR1,DBZI1,DBZC1,NLICE1,NRAIN1)
 
 !
       use params_mod, only: dbzmin, epsq, tfrz, eps, rd, d608
@@ -299,11 +328,12 @@ SUBROUTINE CALMICT_new(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL,     &
 !
 !-- For the old version of the microphysics:
 !
-      SUBROUTINE CALMICT_old(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL,     &
-                        QW1,QI1,QR1,QS1,DBZ1,DBZR1,DBZI1,DBZC1,NLICE1,NRAIN1)
+      SUBROUTINE CALMICT_old(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL, &
+                  QW1,QI1,QR1,QS1,DBZ1,DBZR1,DBZI1,DBZC1,NLICE1,NRAIN1)
+!-----------------------------------------------------------------------
 !> CALMICT_old computes hydrometeors from the older version of the microphysics.
 !>
-!> This routin computes the mixing ratios of cloud water, cloud ice, 
+!> This routine computes the mixing ratios of cloud water, cloud ice, 
 !> rain, and snow. The code is based on option MP_PHYSICS==95 in the
 !> WRF namelist and option MICRO='fer' in NMMB configure files.
 !>
@@ -315,14 +345,16 @@ SUBROUTINE CALMICT_old(P1D,T1D,Q1D,C1D,FI1D,FR1D,FS1D,CUREFL,     &
 !> @param[in] FR1D F_rain (fraction of liquid water in form of rain).
 !> @param[in] FS1D F_RimeF ("Rime Factor", ratio of total ice growth to deposition growth).
 !> @param[in] CUREFL Radar reflectivity contribution from convection (mm**6/m**3).
-!> @param[out] QW1 Cloud water mixing ratio (kg/kg).
-!> @param[out] QI1 Cloud ice mixing ratio (kg/kg).
-!> @param[out] QR1 Rain mixing ratio (kg/kg).
-!> @param[out] QS1 "Snow" (precipitation ice) mixing ratio (kg/kg).
-!> @param[out] DBZ1 Equivalent radar reflectivity factor in dBZ; i.e., 10*LOG10(Z).
-!> @param[out] DBZR Equivalent radar reflectivity factor from rain in dBZ.
-!> @param[out] DBZI Equivalent radar reflectivity factor from ice (all forms) in dBZ.
-!> @param[out] DBZC Equivalent radar reflectivity factor from parameterized convection in dBZ.
+!> @param[inout] QW1 Cloud water mixing ratio (kg/kg).
+!> @param[inout] QI1 Cloud ice mixing ratio (kg/kg).
+!> @param[inout] QR1 Rain mixing ratio (kg/kg).
+!> @param[inout] QS1 "Snow" (precipitation ice) mixing ratio (kg/kg).
+!> @param[inout] DBZ1 Equivalent radar reflectivity factor in dBZ; i.e., 10*LOG10(Z).
+!> @param[inout] DBZR1 Equivalent radar reflectivity factor from rain in dBZ.
+!> @param[inout] DBZI1 Equivalent radar reflectivity factor from ice (all forms) in dBZ.
+!> @param[inout] DBZC1 Equivalent radar reflectivity factor from parameterized convection in dBZ.
+!> @param[inout] NLICE1 Time-averaged number concentration of large ice. 
+!> @param[inout] NRAIN1 Number concentration of rain drops (m).
 !>
 !> ### Program history log:
 !> Date | Programmer | Comments

sorc/ncep_post.fd/CALPBL.f

@@ -1,10 +1,10 @@
 !> @file
-!> @brief Subroutine that computes PBL height based on bulk RCH number.
+!> @brief Subroutine that computes PBL height based on bulk Richardson number.
 !>
 !> This routine computes the bulk Richardson number
 !> and PBL height above surface.
 !>     
-!> @param[out] PBLRI PBL height above ground.
+!> @param[inout] PBLRI real PBL height above ground.
 !>
 !> ### Program history log:
 !> Date | Programmer | Comments
@@ -13,6 +13,11 @@
 !> 2021-09-02 | Bo Cui     | Decompose UPP in X direction          
 !>   
 !> @author M Tsidulko @date 2006-05-04
+!-----------------------------------------------------------------------
+!> @brief Subroutine that computes PBL height based on bulk Richardson number.
+!>
+!> @param[inout] PBLRI real PBL height above ground.
+!-----------------------------------------------------------------------
       SUBROUTINE CALPBL(PBLRI)
 
 !
@@ -183,7 +188,7 @@ SUBROUTINE CALPBL(PBLRI)
 !  IF BULK RICHARDSON NUMBER (RIB) EXCEEDS THE CRITICAL RICHARDSON
 !  NUMBER (RICR), DETERMINE ABL HEIGHT USING LINEAR INTERPOLATION
 !  BETWEEN HEIGHTS, AND PREVIOUS (RIBP) AND CURRENT (RIB) BULK
-!  RICHARDSON NUMBERS.  L IS BOUNDARY-LAYER TOP LEVEL NUMBER.
+!  RICHARDSON NUMBERS. L IS BOUNDARY-LAYER TOP LEVEL NUMBER.
 ! --------------------------------------------------------------------
             IF (RIB>=RICR.AND.ICALPBL(I,J)==0) THEN
               PBLRI(I,J) = ZMID(I,J,L)+(ZMID(I,J,L-1)-ZMID(I,J,L))*      &