From 0356c63785ef55edf3a5efbc70a44262bc1635be Mon Sep 17 00:00:00 2001
From: Caroline Cardinale <Caroline.Cardinale@gaea9.ncrc.gov>
Date: Wed, 21 Jun 2017 09:31:22 -0400
Subject: [PATCH] Added doxygen comments to MOM_domains.F90

Added doxygen comments to all of the subroutines in MOM_domains.F90. All the
answers are bitwise identical.
---
 src/framework/MOM_domains.F90 | 563 ++++++++++++++++++++++++++--------
 1 file changed, 430 insertions(+), 133 deletions(-)

diff --git a/src/framework/MOM_domains.F90 b/src/framework/MOM_domains.F90
index ca1dc281a2..018ec6cf56 100644
--- a/src/framework/MOM_domains.F90
+++ b/src/framework/MOM_domains.F90
@@ -139,13 +139,26 @@ module MOM_domains
 
 contains
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_var_3d(array, MOM_dom, sideflag, complete, position, halo)
-  real, dimension(:,:,:), intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: position
-  integer,      optional, intent(in)    :: halo
+  real, dimension(:,:,:), intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! sothe halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                                    !! halo updates should be completed before
+                                                    !! progress resumes. Omitting complete is the
+                                                    !! same as setting complete to .true.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER by
+                                                    !! default.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: array - The array which is having its halos points exchanged.
 !  (in)      MOM_dom - The MOM_domain_type containing the mpp_domain needed to
 !                      determine where data should be sent.
@@ -180,14 +193,25 @@ subroutine pass_var_3d(array, MOM_dom, sideflag, complete, position, halo)
 
 end subroutine pass_var_3d
 
-
+! #@# This subroutine needs a doxygen description
 subroutine pass_var_2d(array, MOM_dom, sideflag, complete, position, halo)
-  real, dimension(:,:),  intent(inout) :: array
-  type(MOM_domain_type), intent(inout) :: MOM_dom
-  integer,     optional, intent(in)    :: sideflag
-  logical,     optional, intent(in)    :: complete
-  integer,     optional, intent(in)    :: position
-  integer,     optional, intent(in)    :: halo
+  real, dimension(:,:),  intent(inout) :: array    !< The array which is having its halos points
+                                                   !! exchanged.
+  type(MOM_domain_type), intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                   !! needed to determine where data should be sent.
+  integer,     optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  logical,     optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                                   !! halo updates should be completed before
+                                                   !! progress resumes.  Omitting complete is the
+                                                   !! same as setting complete to .true.
+  integer,     optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                   !!  This is usally CORNER, but is CENTER
+                                                   !! by default.
+  integer,     optional, intent(in)    :: halo     !< The size of the halo to update - the full halo
+                                                   !! by default.
 ! Arguments: array - The array which is having its halos points exchanged.
 !  (in)      MOM_dom - The MOM_domain_type containing the mpp_domain needed to
 !                      determine where data should be sent.
@@ -224,13 +248,25 @@ subroutine pass_var_2d(array, MOM_dom, sideflag, complete, position, halo)
 end subroutine pass_var_2d
 
 function pass_var_start_2d(array, MOM_dom, sideflag, position, complete, halo)
-  real, dimension(:,:),   intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: halo
-  integer :: pass_var_start_2d
+  real, dimension(:,:),   intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                                    !! halo updates should be completed before
+                                                    !! progress resumes.  Omitting complete is the
+                                                    !! same as setting complete to .true.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
+  integer                               :: pass_var_start_2d  !<The integer index for this update.
 ! Arguments: array - The array which is having its halos points exchanged.
 !  (in)      MOM_dom - The MOM_domain_type containing the mpp_domain needed to
 !                      determine where data should be sent.
@@ -264,13 +300,25 @@ function pass_var_start_2d(array, MOM_dom, sideflag, position, complete, halo)
 end function pass_var_start_2d
 
 function pass_var_start_3d(array, MOM_dom, sideflag, position, complete, halo)
-  real, dimension(:,:,:), intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: halo
-  integer                               :: pass_var_start_3d
+  real, dimension(:,:,:), intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                                    !! halo updates should be completed before
+                                                    !! progress resumes.  Omitting complete is the
+                                                    !! same as setting complete to .true.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
+  integer                               :: pass_var_start_3d  !< The integer index for this update.
 ! Arguments: array - The array which is having its halos points exchanged.
 !  (in)      MOM_dom - The MOM_domain_type containing the mpp_domain needed to
 !                      determine where data should be sent.
@@ -303,13 +351,25 @@ function pass_var_start_3d(array, MOM_dom, sideflag, position, complete, halo)
   endif
 end function pass_var_start_3d
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_var_complete_2d(id_update, array, MOM_dom, sideflag, position, halo)
-  integer,                intent(in)    :: id_update
-  real, dimension(:,:),   intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  integer,      optional, intent(in)    :: halo
+  integer,                intent(in)    :: id_update !< The integer id of this update which has
+                                                    !! been returned from a previous call to
+                                                    !! pass_var_start.
+  real, dimension(:,:),   intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: id_update - The integer id of this update which has been returned
 !                        from a previous call to pass_var_start.
 !  (inout)   array - The array which is having its halos points exchanged.
@@ -340,13 +400,25 @@ subroutine pass_var_complete_2d(id_update, array, MOM_dom, sideflag, position, h
 
 end subroutine pass_var_complete_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_var_complete_3d(id_update, array, MOM_dom, sideflag, position, halo)
-  integer,                intent(in)    :: id_update
-  real, dimension(:,:,:), intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  integer,      optional, intent(in)    :: halo
+  integer,                intent(in)    :: id_update !< The integer id of this update which has
+                                                    !! been returned from a previous call to
+                                                    !! pass_var_start.
+  real, dimension(:,:,:), intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: id_update - The integer id of this update which has been returned
 !                        from a previous call to pass_var_start.
 !  (inout)   array - The array which is having its halos points exchanged.
@@ -377,14 +449,31 @@ subroutine pass_var_complete_3d(id_update, array, MOM_dom, sideflag, position, h
 
 end subroutine pass_var_complete_3d
 
-
+! #@# This subroutine needs a doxygen description
 subroutine pass_vector_2d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete, halo)
-  real, dimension(:,:),  intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type), intent(inout) :: MOM_dom
-  integer,     optional, intent(in)    :: direction
-  integer,     optional, intent(in)    :: stagger
-  logical,     optional, intent(in)    :: complete
-  integer,     optional, intent(in)    :: halo
+  real, dimension(:,:),  intent(inout) :: u_cmpt    !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:),  intent(inout) :: v_cmpt    !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type), intent(inout) :: MOM_dom   !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,     optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,     optional, intent(in)    :: stagger   !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  logical,     optional, intent(in)    :: complete  !< An optional argument indicating whether the
+                                     !! halo updates should be completed before progress resumes.
+                                     !! Omitting complete is the same as setting complete to .true.
+  integer,     optional, intent(in)    :: halo      !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: u_cmpt - The nominal zonal (u) component of the vector pair which
 !                     is having its halos points exchanged.
 !  (inout)   v_cmpt - The nominal meridional (v) component of the vector pair
@@ -431,11 +520,21 @@ subroutine pass_vector_2d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete,
 
 end subroutine pass_vector_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine fill_vector_symmetric_edges_2d(u_cmpt, v_cmpt, MOM_dom, stagger, scalar)
-  real, dimension(:,:),  intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type), intent(inout) :: MOM_dom
-  integer,     optional, intent(in)    :: stagger
-  logical,     optional, intent(in)    :: scalar
+  real, dimension(:,:),  intent(inout) :: u_cmpt  !< The nominal zonal (u) component of the vector
+                                                  !! pair which is having its halos points
+                                                  !! exchanged.
+  real, dimension(:,:),  intent(inout) :: v_cmpt  !< The nominal meridional (v) component of the
+                                                  !! vector pair which is having its halos points
+                                                  !! exchanged.
+  type(MOM_domain_type), intent(inout) :: MOM_dom !< The MOM_domain_type containing the mpp_domain
+                                                  !! needed to determine where data should be
+                                                  !! sent.
+  integer,     optional, intent(in)    :: stagger !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  logical,     optional, intent(in)    :: scalar !< An optional argument indicating whether.
 ! Arguments: u_cmpt - The nominal zonal (u) component of the vector pair which
 !                     is having its halos points exchanged.
 !  (inout)   v_cmpt - The nominal meridional (v) component of the vector pair
@@ -506,13 +605,31 @@ subroutine fill_vector_symmetric_edges_2d(u_cmpt, v_cmpt, MOM_dom, stagger, scal
 
 end subroutine fill_vector_symmetric_edges_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_vector_3d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete, halo)
-  real, dimension(:,:,:), intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: halo
+  real, dimension(:,:,:), intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:,:), intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                     !! halo updates should be completed before progress resumes.
+                                     !! Omitting complete is the same as setting complete to .true.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: u_cmpt - The nominal zonal (u) component of the vector pair which
 !                     is having its halos points exchanged.
 !  (inout)   v_cmpt - The nominal meridional (v) component of the vector pair
@@ -560,13 +677,31 @@ subroutine pass_vector_3d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete,
 end subroutine pass_vector_3d
 
 function pass_vector_start_2d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete, halo)
-  real, dimension(:,:),   intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: halo
-  integer                               :: pass_vector_start_2d
+  real, dimension(:,:),   intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:),   intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                     !! halo updates should be completed before progress resumes.
+                                     !! Omitting complete is the same as setting complete to .true.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
+  integer                               :: pass_vector_start_2d !< The integer index for this
+                                                                !! update.
 ! Arguments: u_cmpt - The nominal zonal (u) component of the vector pair which
 !                     is having its halos points exchanged.
 !  (inout)   v_cmpt - The nominal meridional (v) component of the vector pair
@@ -612,13 +747,31 @@ function pass_vector_start_2d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, compl
 end function pass_vector_start_2d
 
 function pass_vector_start_3d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, complete, halo)
-  real, dimension(:,:,:), intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  logical,      optional, intent(in)    :: complete
-  integer,      optional, intent(in)    :: halo
-  integer                               :: pass_vector_start_3d
+  real, dimension(:,:,:), intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:,:), intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  logical,      optional, intent(in)    :: complete !< An optional argument indicating whether the
+                                     !! halo updates should be completed before progress resumes.
+                                     !! Omitting complete is the same as setting complete to .true.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
+  integer                               :: pass_vector_start_3d !< The integer index for this
+                                                                !! update.
 ! Arguments: u_cmpt - The nominal zonal (u) component of the vector pair which
 !                     is having its halos points exchanged.
 !  (inout)   v_cmpt - The nominal meridional (v) component of the vector pair
@@ -663,13 +816,31 @@ function pass_vector_start_3d(u_cmpt, v_cmpt, MOM_dom, direction, stagger, compl
 
 end function pass_vector_start_3d
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_vector_complete_2d(id_update, u_cmpt, v_cmpt, MOM_dom, direction, stagger, halo)
-  integer,                intent(in)    :: id_update
-  real, dimension(:,:),   intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  integer,      optional, intent(in)    :: halo
+  integer,                intent(in)    :: id_update !< The integer id of this update which has been
+                                                    !! returned from a previous call to
+                                                    !! pass_var_start.
+  real, dimension(:,:),   intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:),   intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: id_update - The integer id of this update which has been returned
 !                        from a previous call to pass_var_start.
 !  (inout)   u_cmpt - The nominal zonal (u) component of the vector pair which
@@ -712,13 +883,31 @@ subroutine pass_vector_complete_2d(id_update, u_cmpt, v_cmpt, MOM_dom, direction
 
 end subroutine pass_vector_complete_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine pass_vector_complete_3d(id_update, u_cmpt, v_cmpt, MOM_dom, direction, stagger, halo)
-  integer,                intent(in)    :: id_update
-  real, dimension(:,:,:), intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  integer,      optional, intent(in)    :: halo
+  integer,                intent(in)    :: id_update !< The integer id of this update which has been
+                                                    !! returned from a previous call to
+                                                    !! pass_var_start.
+  real, dimension(:,:,:), intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:,:), intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments: id_update - The integer id of this update which has been returned
 !                        from a previous call to pass_var_start.
 !  (inout)   u_cmpt - The nominal zonal (u) component of the vector pair which
@@ -761,14 +950,26 @@ subroutine pass_vector_complete_3d(id_update, u_cmpt, v_cmpt, MOM_dom, direction
 
 end subroutine pass_vector_complete_3d
 
+! #@# This subroutine needs a doxygen description
 subroutine create_var_group_pass_2d(group, array, MOM_dom, sideflag, position, &
                                     halo)
-  type(group_pass_type),  intent(inout) :: group
-  real, dimension(:,:),   intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  integer,      optional, intent(in)    :: halo
+  type(group_pass_type),  intent(inout) :: group    !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  real, dimension(:,:),   intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments:
 !  (inout)   group - The data type that store information for group update.
 !                    This data will be used in do_group_pass.
@@ -802,13 +1003,25 @@ subroutine create_var_group_pass_2d(group, array, MOM_dom, sideflag, position, &
 
 end subroutine create_var_group_pass_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine create_var_group_pass_3d(group, array, MOM_dom, sideflag, position, halo)
-  type(group_pass_type),  intent(inout) :: group
-  real, dimension(:,:,:), intent(inout) :: array
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: sideflag
-  integer,      optional, intent(in)    :: position
-  integer,      optional, intent(in)    :: halo
+  type(group_pass_type),  intent(inout) :: group    !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  real, dimension(:,:,:), intent(inout) :: array    !< The array which is having its halos points
+                                                    !! exchanged.
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: sideflag !< An optional integer indicating which
+      !! directions the data should be sent. It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH.  For example, TO_EAST sends the data to the processor to the east,
+      !! so the halos on the western side are filled.  TO_ALL is the default if sideflag is omitted.
+  integer,      optional, intent(in)    :: position !< An optional argument indicating the position.
+                                                    !! This is usally CORNER, but is CENTER
+                                                    !! by default.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments:
 !  (inout)   group - The data type that store information for group update.
 !                    This data will be used in do_group_pass.
@@ -842,14 +1055,32 @@ subroutine create_var_group_pass_3d(group, array, MOM_dom, sideflag, position, h
 
 end subroutine create_var_group_pass_3d
 
-
+! #@# This subroutine needs a doxygen description
 subroutine create_vector_group_pass_2d(group, u_cmpt, v_cmpt, MOM_dom, direction, stagger, halo)
-  type(group_pass_type),  intent(inout) :: group
-  real, dimension(:,:),   intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  integer,      optional, intent(in)    :: halo
+  type(group_pass_type),  intent(inout) :: group    !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  real, dimension(:,:),   intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:),   intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments:
 !  (inout)   group - The data type that store information for group update.
 !                    This data will be used in do_group_pass.
@@ -894,13 +1125,32 @@ subroutine create_vector_group_pass_2d(group, u_cmpt, v_cmpt, MOM_dom, direction
 
 end subroutine create_vector_group_pass_2d
 
+! #@# This subroutine needs a doxygen description
 subroutine create_vector_group_pass_3d(group, u_cmpt, v_cmpt, MOM_dom, direction, stagger, halo)
-  type(group_pass_type),  intent(inout) :: group
-  real, dimension(:,:,:), intent(inout) :: u_cmpt, v_cmpt
-  type(MOM_domain_type),  intent(inout) :: MOM_dom
-  integer,      optional, intent(in)    :: direction
-  integer,      optional, intent(in)    :: stagger
-  integer,      optional, intent(in)    :: halo
+  type(group_pass_type),  intent(inout) :: group    !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  real, dimension(:,:,:), intent(inout) :: u_cmpt   !< The nominal zonal (u) component of the vector
+                                                    !! pair which is having its halos points
+                                                    !! exchanged.
+  real, dimension(:,:,:), intent(inout) :: v_cmpt   !< The nominal meridional (v) component of the
+                                                    !! vector pair which is having its halos points
+                                                    !! exchanged.
+
+  type(MOM_domain_type),  intent(inout) :: MOM_dom  !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
+  integer,      optional, intent(in)    :: direction !< An optional integer indicating which
+      !! directions the data should be sent.  It is TO_ALL or the sum of any of TO_EAST, TO_WEST,
+      !! TO_NORTH, and TO_SOUTH, possibly plus SCALAR_PAIR if these are paired non-directional
+      !! scalars discretized at the typical vector component locations.  For example, TO_EAST sends
+      !! the data to the processor to the east, so the halos on the western side are filled. TO_ALL
+      !! is the default if omitted.
+  integer,      optional, intent(in)    :: stagger  !< An optional flag, which may be one of A_GRID,
+                     !! BGRID_NE, or CGRID_NE, indicating where the two components of the vector are
+                     !! discretized. Omitting stagger is the same as setting it to CGRID_NE.
+  integer,      optional, intent(in)    :: halo     !< The size of the halo to update - the full
+                                                    !! halo by default.
 ! Arguments:
 !  (inout)   group - The data type that store information for group update.
 !                    This data will be used in do_group_pass.
@@ -946,9 +1196,14 @@ subroutine create_vector_group_pass_3d(group, u_cmpt, v_cmpt, MOM_dom, direction
 
 end subroutine create_vector_group_pass_3d
 
+! #@# This subroutine needs a doxygen description
 subroutine do_group_pass(group, MOM_dom)
-  type(group_pass_type), intent(inout) :: group
-  type(MOM_domain_type), intent(inout) :: MOM_dom
+  type(group_pass_type), intent(inout) :: group     !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  type(MOM_domain_type), intent(inout) :: MOM_dom   !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
   real                                 :: d_type
 
 ! Arguments:
@@ -960,9 +1215,14 @@ subroutine do_group_pass(group, MOM_dom)
 
 end subroutine do_group_pass
 
+! #@# This subroutine needs a doxygen description
 subroutine start_group_pass(group, MOM_dom)
-  type(group_pass_type), intent(inout) :: group
-  type(MOM_domain_type), intent(inout) :: MOM_dom
+  type(group_pass_type), intent(inout) :: group     !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  type(MOM_domain_type), intent(inout) :: MOM_dom   !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
   real                                 :: d_type
 
 ! Arguments:
@@ -974,9 +1234,14 @@ subroutine start_group_pass(group, MOM_dom)
 
 end subroutine start_group_pass
 
+! #@# This subroutine needs a doxygen description
 subroutine complete_group_pass(group, MOM_dom)
-  type(group_pass_type), intent(inout) :: group
-  type(MOM_domain_type), intent(inout) :: MOM_dom
+  type(group_pass_type), intent(inout) :: group     !< The data type that store information for
+                                                    !! group update. This data will be used in
+                                                    !! do_group_pass.
+  type(MOM_domain_type), intent(inout) :: MOM_dom   !< The MOM_domain_type containing the mpp_domain
+                                                    !! needed to determine where data should be
+                                                    !! sent.
   real                                 :: d_type
 
 ! Arguments:
@@ -988,21 +1253,41 @@ subroutine complete_group_pass(group, MOM_dom)
 
 end subroutine complete_group_pass
 
-
+! #@# This subroutine needs a doxygen description.
 subroutine MOM_domains_init(MOM_dom, param_file, symmetric, static_memory, &
                             NIHALO, NJHALO, NIGLOBAL, NJGLOBAL, NIPROC, NJPROC, &
                             min_halo, domain_name, include_name, param_suffix)
-  type(MOM_domain_type),           pointer       :: MOM_dom
-  type(param_file_type),           intent(in)    :: param_file !< A structure to parse for run-time parameters
-  logical, optional,               intent(in)    :: symmetric
-  logical, optional,               intent(in)    :: static_memory
-  integer, optional,               intent(in)    :: NIHALO, NJHALO
-  integer, optional,               intent(in)    :: NIGLOBAL, NJGLOBAL
-  integer, optional,               intent(in)    :: NIPROC, NJPROC
-  integer, dimension(2), optional, intent(inout) :: min_halo
-  character(len=*),      optional, intent(in)    :: domain_name
-  character(len=*),      optional, intent(in)    :: include_name
-  character(len=*),      optional, intent(in)    :: param_suffix
+  type(MOM_domain_type),           pointer       :: MOM_dom      !< A pointer to the MOM_domain_type
+                                                                 !! being defined here.
+  type(param_file_type),           intent(in)    :: param_file   !< A structure to parse for
+                                                                 !! run-time parameters
+  logical, optional,               intent(in)    :: symmetric    !< If present, this specifies
+                                            !! whether this domain is symmetric, regardless of
+                                            !! whether the macro SYMMETRIC_MEMORY_ is defined.
+  logical, optional,               intent(in)    :: static_memory !< If present and true, this
+                         !! domain type is set up for static memory and error checking of
+                         !! various input values is performed against those in the input file.
+  integer, optional,               intent(in)    :: NIHALO       !< Default halo sizes, required
+                                                                 !! with static memory.
+  integer, optional,               intent(in)    :: NJHALO       !< Default halo sizes, required
+                                                                 !! with static memory.
+  integer, optional,               intent(in)    :: NIGLOBAL     !< Total domain sizes, required
+                                                                 !! with static memory.
+  integer, optional,               intent(in)    :: NJGLOBAL     !< Total domain sizes, required
+                                                                 !! with static memory.
+  integer, optional,               intent(in)    :: NIPROC       !< Processor counts, required with
+                                                                 !! static memory.
+  integer, optional,               intent(in)    :: NJPROC       !< Processor counts, required with
+                                                                 !! static memory.
+  integer, dimension(2), optional, intent(inout) :: min_halo     !< If present, this sets the
+                                        !! minimum halo size for this domain in the x- and y-
+                                        !! directions, and returns the actual halo size used.
+  character(len=*),      optional, intent(in)    :: domain_name  !< A name for this domain, "MOM"
+                                                                 !! if missing.
+  character(len=*),      optional, intent(in)    :: include_name !< A name for model's include file,
+                                                                 !! "MOM_memory.h" if missing.
+  character(len=*),      optional, intent(in)    :: param_suffix !< A suffix to apply to
+                                                                 !! layout-specific parameters.
 
 
 ! Arguments: MOM_dom - A pointer to the MOM_domain_type being defined here.
@@ -1404,6 +1689,7 @@ subroutine MOM_domains_init(MOM_dom, param_file, symmetric, static_memory, &
 
 end subroutine MOM_domains_init
 
+! #@# This subroutine needs a doxygen description and comments.
 subroutine clone_MD_to_MD(MD_in, MOM_dom, min_halo, halo_size, symmetric, &
                           domain_name)
   type(MOM_domain_type),           intent(in)    :: MD_in
@@ -1482,6 +1768,7 @@ subroutine clone_MD_to_MD(MD_in, MOM_dom, min_halo, halo_size, symmetric, &
 
 end subroutine clone_MD_to_MD
 
+! #@# This subroutine needs a doxygen description and comments.
 subroutine clone_MD_to_d2D(MD_in, mpp_domain, min_halo, halo_size, symmetric, &
                            domain_name)
   type(MOM_domain_type),           intent(in)    :: MD_in
@@ -1545,17 +1832,27 @@ subroutine clone_MD_to_d2D(MD_in, mpp_domain, min_halo, halo_size, symmetric, &
 
 end subroutine clone_MD_to_d2D
 
+! #@# This subroutine needs a doxygen description
 subroutine get_domain_extent(Domain, isc, iec, jsc, jec, isd, ied, jsd, jed, &
                              isg, ieg, jsg, jeg, idg_offset, jdg_offset, &
                              symmetric, local_indexing, index_offset)
-  type(MOM_domain_type), intent(in) :: Domain
-  integer, intent(out) :: isc, iec, jsc, jec
-  integer, intent(out) :: isd, ied, jsd, jed
-  integer, intent(out) :: isg, ieg, jsg, jeg
-  integer, intent(out) :: idg_offset, jdg_offset
-  logical, intent(out) :: symmetric
-  logical, optional, intent(in) :: local_indexing
-  integer, optional, intent(in) :: index_offset
+  type(MOM_domain_type), &
+           intent(in)  :: Domain
+  integer, intent(out) :: isc, iec, jsc, jec     !< The start & end indices of the computational
+                                                 !! domain.
+  integer, intent(out) :: isd, ied, jsd, jed     !< The start & end indices of the data domain.
+  integer, intent(out) :: isg, ieg, jsg, jeg     !< The start & end indices of the global domain.
+  integer, intent(out) :: idg_offset, jdg_offset !< The offset between the corresponding global and
+                                                 !! data index spaces.
+  logical, intent(out) :: symmetric              !< True if symmetric memory is used.
+  logical, optional, &
+            intent(in) :: local_indexing         !< If true, local tracer array indices start at 1,
+                                                 !! as in most MOM6 or GOLD code.
+  integer, optional, &
+            intent(in) :: index_offset           !< A fixed additional offset to all indices. This
+                                                 !! can be useful for some types of debugging with
+                                                 !! dynamic memory allocation.
+
 ! Arguments: Domain - The MOM_domain_type from which the indices are extracted.
 !  (out)     isc, iec, jsc, jec - the start & end indices of the
 !                                 computational domain.