Add missing subroutine headers; fix orphan !!, !!IB markers, !!> syntax

sbryngelson · sbryngelson · commit eeece9b7170d · 2026-03-22T20:16:38.000-04:00
diff --git a/src/common/m_compile_specific.f90 b/src/common/m_compile_specific.f90
@@ -12,8 +12,7 @@ module m_compile_specific
 
 contains
 
-    !> Creates a directory and all its parents if it does not exist
-    !! @param dir_name Directory path
+    !> Create a directory and all its parents if it does not exist
     impure subroutine s_create_directory(dir_name)
 
         character(LEN=*), intent(in) :: dir_name
diff --git a/src/common/m_derived_types.fpp b/src/common/m_derived_types.fpp
@@ -236,13 +236,11 @@ module m_derived_types
         real(wp)               :: V0          !< Bubble velocity
         real(wp)               :: p0          !< Bubble size
         real(wp)               :: m0          !< Bubble velocity
-        integer                :: hcid
-        !! id for hard coded initial condition
+        integer                :: hcid        !< Hardcoded initial condition ID
+        real(wp)               :: cf_val      !< Color function value
+        real(wp)               :: Y(1:num_species)
 
-        real(wp) :: cf_val !! color function value
-        real(wp) :: Y(1:num_species)
-
-        !! STL or OBJ model input parameter
+        ! STL or OBJ model input parameter
         character(LEN=pathlen_max) :: model_filepath  !< Path the STL file relative to case_dir.
         real(wp), dimension(1:3) :: model_translate  !< Translation of the STL object.
         real(wp), dimension(1:3) :: model_scale  !< Scale factor for the STL object.
@@ -271,7 +269,7 @@ module m_derived_types
         real(wp)                      :: theta
         logical                       :: slip
 
-        !! STL or OBJ model input parameter
+        ! STL or OBJ model input parameter
         character(LEN=pathlen_max) :: model_filepath  !< Path the STL file relative to case_dir.
         real(wp), dimension(1:3) :: model_translate  !< Translation of the STL object.
         real(wp), dimension(1:3) :: model_scale  !< Scale factor for the STL object.
diff --git a/src/common/m_finite_differences.fpp b/src/common/m_finite_differences.fpp
@@ -13,6 +13,7 @@ module m_finite_differences
 
 contains
 
+    !> Accumulate the finite-difference divergence of a vector field onto a scalar field.
     subroutine s_compute_fd_divergence(div, fields, ix_s, iy_s, iz_s)
 
         type(scalar_field), intent(inout) :: div
diff --git a/src/common/m_helper_basic.fpp b/src/common/m_helper_basic.fpp
@@ -98,6 +98,7 @@ contains
 
     end function f_is_integer
 
+    !> Compute ghost-cell buffer size and set interior/buffered coordinate index bounds.
     subroutine s_configure_coordinate_bounds(recon_type, weno_polyn, muscl_polyn, igr_order, buff_size, idwint, idwbuff, viscous, &
 
         & bubbles_lagrange, m, n, p, num_dims, igr, ib)
diff --git a/src/common/m_model.fpp b/src/common/m_model.fpp
@@ -28,10 +28,8 @@ module m_model
     public :: s_instantiate_STL_models
 #endif
 
-    !! array of STL models that can be allocated and then used in IB marker and levelset compute
-    type(t_model_array), allocatable, target :: models(:)
-    !! GPU-friendly flat arrays for STL model data
-    integer, allocatable                      :: gpu_ntrs(:)
+    type(t_model_array), allocatable, target  :: models(:)    !< STL/OBJ models for IB markers and levelset
+    integer, allocatable                      :: gpu_ntrs(:)  !< GPU-friendly flat arrays for STL model data
     real(wp), allocatable, dimension(:,:,:,:) :: gpu_trs_v
     real(wp), allocatable, dimension(:,:,:)   :: gpu_trs_n
     real(wp), allocatable, dimension(:,:,:,:) :: gpu_boundary_v
@@ -414,6 +412,7 @@ contains
 
     end subroutine s_model_free
 
+    !> Read the next non-blank, non-comment line from an STL or OBJ model file.
     impure function f_read_line(iunit, line) result(bIsLine)
 
         integer, intent(in)        :: iunit
@@ -964,6 +963,7 @@ contains
     end subroutine s_distance_normals_2D
 
 #ifdef MFC_SIMULATION
+    !> Load, transform, and register STL/OBJ immersed-boundary models onto the simulation grid.
     subroutine s_instantiate_STL_models()
 
         ! Variables for IBM+STL
@@ -1126,6 +1126,7 @@ contains
     end subroutine s_instantiate_STL_models
 #endif
 
+    !> Pack triangle vertices and normals from a model into flat arrays for GPU transfer.
     subroutine s_pack_model_for_gpu(ma)
 
         type(t_model_array), intent(inout) :: ma
diff --git a/src/common/m_mpi_common.fpp b/src/common/m_mpi_common.fpp
@@ -22,7 +22,6 @@ module m_mpi_common
 
     integer, private :: v_size
     $:GPU_DECLARE(create='[v_size]')
-    !! Generic flags used to identify and report MPI errors
 
     !> This variable is utilized to pack and send the buffer of the cell-average primitive variables, for a single computational
     !! domain boundary at the time, to the relevant neighboring processor.
@@ -99,6 +98,7 @@ contains
 
     end subroutine s_mpi_initialize
 
+    !> Set up MPI I/O data views and variable pointers for parallel file output.
     impure subroutine s_initialize_mpi_data(q_cons_vf, ib_markers, beta)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_cons_vf
@@ -180,6 +180,7 @@ contains
 
     end subroutine s_initialize_mpi_data
 
+    !> Set up MPI I/O data views for downsampled (coarsened) parallel file output.
     subroutine s_initialize_mpi_data_ds(q_cons_vf)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_cons_vf
@@ -401,9 +402,7 @@ contains
 
     end subroutine s_mpi_allreduce_max
 
-    !> Reduce a local real value to its global minimum and broadcast the result to all ranks.
-    ! ! @param var_loc holds the local value to be reduced among all the processors in communicator. On output, the variable holds
-    ! the minimum value, reduced amongst all of the local values.
+    !> Reduce a local real value to its global minimum across all ranks
     impure subroutine s_mpi_reduce_min(var_loc)
 
         real(wp), intent(inout) :: var_loc
@@ -422,9 +421,7 @@ contains
     end subroutine s_mpi_reduce_min
 
     !> Reduce a 2-element variable to its global maximum value with the owning processor rank (MPI_MAXLOC).
-    ! ! @param var_loc On input, this variable holds the local value and processor rank, which are to be reduced among all the
-    ! processors in communicator. On output, this variable holds the maximum value, reduced amongst all of the local values, and the
-    ! process rank to which the value belongs.
+    !> Reduce a local value to its global maximum with location (rank) across all ranks
     impure subroutine s_mpi_reduce_maxloc(var_loc)
 
         real(wp), dimension(2), intent(inout) :: var_loc
diff --git a/src/common/m_variables_conversion.fpp b/src/common/m_variables_conversion.fpp
@@ -37,7 +37,7 @@ module m_variables_conversion
 #endif
     s_finalize_variables_conversion_module
 
-    !! In simulation, gammas, pi_infs, and qvs are already declared in m_global_variables
+    ! In simulation, gammas, pi_infs, and qvs are already declared in m_global_variables
 #ifndef MFC_SIMULATION
     real(wp), allocatable, public, dimension(:) :: gammas, gs_min, pi_infs, ps_inf, cvs, qvs, qvps
     $:GPU_DECLARE(create='[gammas, gs_min, pi_infs, ps_inf, cvs, qvs, qvps]')
diff --git a/src/post_process/m_data_output.fpp b/src/post_process/m_data_output.fpp
@@ -1114,6 +1114,7 @@ contains
 
     end subroutine s_write_lag_variable_to_formatted_database_file
 
+    !> Convert the binary immersed-boundary state file to per-body formatted text files
     impure subroutine s_write_ib_state_files()
 
         character(len=len_trim(case_dir) + 4*name_len) :: in_file, out_file, file_loc
diff --git a/src/post_process/m_mpi_proxy.fpp b/src/post_process/m_mpi_proxy.fpp
@@ -138,9 +138,7 @@ contains
 
     end subroutine s_mpi_bcast_user_inputs
 
-    !> Gather the Silo database metadata for the spatial extents to boost the performance of the multidimensional visualization.
-    ! ! @param spatial_extents Spatial extents for each processor's sub-domain. First dimension corresponds to the minimum and
-    ! maximum values, respectively, while the second dimension corresponds to the processor rank.
+    !> Gather spatial extents from all ranks for Silo database metadata
     impure subroutine s_mpi_gather_spatial_extents(spatial_extents)
 
         real(wp), dimension(1:, 0:), intent(inout) :: spatial_extents
diff --git a/src/post_process/m_start_up.fpp b/src/post_process/m_start_up.fpp
@@ -725,7 +725,7 @@ contains
         end if
 
         if (bubbles_lagrange) then
-            !! Void fraction field
+            ! Void fraction field
             q_sf(:,:,:) = 1._wp - q_cons_vf(beta_idx)%sf(-offset_x%beg:m + offset_x%end, -offset_y%beg:n + offset_y%end, &
                  & -offset_z%beg:p + offset_z%end)
             write (varname, '(A)') 'voidFraction'
diff --git a/src/pre_process/m_check_ib_patches.fpp b/src/pre_process/m_check_ib_patches.fpp
@@ -209,8 +209,7 @@ contains
 
     end subroutine s_check_model_ib_patch_geometry
 
-    !!>  This subroutine verifies that the geometric parameters of
-    !! the inactive patch remain unaltered by the user inputs. @param patch_id Patch identifier
+    !> Verify that inactive IB patch geometry parameters remain at defaults
     impure subroutine s_check_inactive_ib_patch_geometry(patch_id)
 
         integer, intent(in) :: patch_id
diff --git a/src/pre_process/m_check_patches.fpp b/src/pre_process/m_check_patches.fpp
@@ -243,6 +243,7 @@ contains
 
     end subroutine s_check_sphere_patch_geometry
 
+    !> Validate geometry parameters for a 2D modal (Fourier) patch
     impure subroutine s_check_2d_modal_patch_geometry(patch_id)
 
         integer, intent(in) :: patch_id
@@ -257,6 +258,7 @@ contains
 
     end subroutine s_check_2d_modal_patch_geometry
 
+    !> Validate geometry parameters for a 3D spherical harmonic patch
     impure subroutine s_check_3d_spherical_harmonic_patch_geometry(patch_id)
 
         integer, intent(in) :: patch_id
@@ -356,8 +358,7 @@ contains
 
     end subroutine s_check_ellipsoid_patch_geometry
 
-    !!>  This subroutine verifies that the geometric parameters of
-    !! the inactive patch remain unaltered by the user inputs. @param patch_id Patch identifier
+    !> Verify that inactive patch geometry parameters remain at defaults
     impure subroutine s_check_inactive_patch_geometry(patch_id)
 
         integer, intent(in) :: patch_id
diff --git a/src/pre_process/m_global_parameters.fpp b/src/pre_process/m_global_parameters.fpp
@@ -153,9 +153,7 @@ module m_global_parameters
     type(ic_patch_parameters), dimension(num_patches_max)    :: patch_icpp
     integer                                                  :: num_bc_patches  !< Number of boundary condition patches
     logical                                                  :: bc_io           !< whether or not to save BC data
-    type(bc_patch_parameters), dimension(num_bc_patches_max) :: patch_bc
-    !! Database of the boundary condition patch parameters for each of the patches employed in the configuration of the boundary
-    !! conditions
+    type(bc_patch_parameters), dimension(num_bc_patches_max) :: patch_bc        !< Boundary condition patch parameters
 
     ! Fluids Physical Parameters
     !> Database of the physical parameters of each of the fluids that is present in the flow. These include the stiffened gas
@@ -179,14 +177,11 @@ module m_global_parameters
 
     !> @name Immersed Boundaries
     !> @{
-    logical                                               :: ib       !< Turn immersed boundaries on
-    integer                                               :: num_ibs  !< Number of immersed boundaries
+    logical                                               :: ib        !< Turn immersed boundaries on
+    integer                                               :: num_ibs   !< Number of immersed boundaries
     integer                                               :: Np
-    type(ib_patch_parameters), dimension(num_patches_max) :: patch_ib
+    type(ib_patch_parameters), dimension(num_patches_max) :: patch_ib  !< Immersed boundary patch parameters
     type(vec3_dt), allocatable, dimension(:)              :: airfoil_grid_u, airfoil_grid_l
-    !! Database of the immersed boundary patch parameters for each of the patches employed in the configuration of the initial
-    !! condition. Note that the maximum allowable number of patches, num_patches_max, may be changed in the module
-    !! m_derived_types.f90.
     !> @}
 
     !> @name Non-polytropic bubble gas compression
diff --git a/src/pre_process/m_icpp_patches.fpp b/src/pre_process/m_icpp_patches.fpp
@@ -982,8 +982,7 @@ contains
         @:HardcodedDimensionsExtrusion()
         @:Hardcoded3DVariables()
 
-        !! Variables to initialize the pressure field that corresponds to the bubble-collapse test case found in Tiwari et al.
-        !! (2013)
+        ! Variables to initialize the pressure field that corresponds to the bubble-collapse test case found in Tiwari et al. (2013)
 
         ! Transferring spherical patch's radius, centroid, smoothing patch identity and smoothing coefficient information
         x_centroid = patch_icpp(patch_id)%x_centroid
diff --git a/src/simulation/m_cbc.fpp b/src/simulation/m_cbc.fpp
@@ -23,25 +23,25 @@ module m_cbc
 
     private; public :: s_initialize_cbc_module, s_cbc, s_finalize_cbc_module
 
-    !! The cell-average primitive variables. They are obtained by reshaping (RS) q_prim_vf in the coordinate direction normal to the
-    !! domain boundary along which the CBC is applied.
+    ! The cell-average primitive variables. They are obtained by reshaping (RS) q_prim_vf in the coordinate direction normal to the
+    ! domain boundary along which the CBC is applied.
 
     real(wp), allocatable, dimension(:,:,:,:) :: q_prim_rsx_vf
     real(wp), allocatable, dimension(:,:,:,:) :: q_prim_rsy_vf
     real(wp), allocatable, dimension(:,:,:,:) :: q_prim_rsz_vf
     $:GPU_DECLARE(create='[q_prim_rsx_vf, q_prim_rsy_vf, q_prim_rsz_vf]')
 
-    !! Cell-average fluxes (src - source). These are directly determined from the cell-average primitive variables, q_prims_rs_vf,
-    !! and not a Riemann solver.
+    ! Cell-average fluxes (src - source). These are directly determined from the cell-average primitive variables, q_prims_rs_vf,
+    ! and not a Riemann solver.
 
     real(wp), allocatable, dimension(:,:,:,:) :: F_rsx_vf, F_src_rsx_vf
     real(wp), allocatable, dimension(:,:,:,:) :: F_rsy_vf, F_src_rsy_vf
     real(wp), allocatable, dimension(:,:,:,:) :: F_rsz_vf, F_src_rsz_vf
     $:GPU_DECLARE(create='[F_rsx_vf, F_src_rsx_vf, F_rsy_vf, F_src_rsy_vf, F_rsz_vf, F_src_rsz_vf]')
 
-    !! There is a CCE bug that is causing some subset of these variables to interfere with variables of the same name in
-    !! m_riemann_solvers.fpp, and giving this versions unique "_l" names works around the bug. Other private module allocatable
-    !! arrays in `acc declare create` clauses don't have this problem, so we still need to isolate this bug.
+    ! There is a CCE bug that is causing some subset of these variables to interfere with variables of the same name in
+    ! m_riemann_solvers.fpp, and giving this versions unique "_l" names works around the bug. Other private module allocatable
+    ! arrays in `acc declare create` clauses don't have this problem, so we still need to isolate this bug.
 
     real(wp), allocatable, dimension(:,:,:,:) :: flux_rsx_vf_l, flux_src_rsx_vf_l
     real(wp), allocatable, dimension(:,:,:,:) :: flux_rsy_vf_l, flux_src_rsy_vf_l
@@ -63,8 +63,8 @@ module m_cbc
     real(wp), allocatable, dimension(:,:,:) :: pi_coef_z  !< Polynomial interpolant coefficients in z-dir
     $:GPU_DECLARE(create='[ds, fd_coef_x, fd_coef_y, fd_coef_z, pi_coef_x, pi_coef_y, pi_coef_z]')
 
-    !! The first dimension of the array identifies the polynomial, the second dimension identifies the position of its coefficients
-    !! and the last dimension denotes the location of the CBC.
+    ! The first dimension of the array identifies the polynomial, the second dimension identifies the position of its coefficients
+    ! and the last dimension denotes the location of the CBC.
 
     type(int_bounds_info) :: is1, is2, is3  !< Indical bounds in the s1-, s2- and s3-directions
     $:GPU_DECLARE(create='[is1, is2, is3]')
@@ -76,8 +76,8 @@ module m_cbc
     $:GPU_DECLARE(create='[dj, bcxb, bcxe, bcyb, bcye, bczb, bcze]')
     $:GPU_DECLARE(create='[cbc_dir, cbc_loc, flux_cbc_index]')
 
-    !! GRCBC inputs for subsonic inflow and outflow conditions consisting of inflow velocities, pressure, density and void fraction
-    !! as well as outflow velocities and pressure
+    ! GRCBC inputs for subsonic inflow and outflow conditions consisting of inflow velocities, pressure, density and void fraction
+    ! as well as outflow velocities and pressure
 
     real(wp), allocatable, dimension(:)   :: pres_in, pres_out, Del_in, Del_out
     real(wp), allocatable, dimension(:,:) :: vel_in, vel_out
diff --git a/src/simulation/m_checker.fpp b/src/simulation/m_checker.fpp
@@ -91,6 +91,7 @@ contains
 
     end subroutine s_check_inputs_time_stepping
 
+    !> Validate NVIDIA unified virtual memory configuration parameters
     impure subroutine s_check_inputs_nvidia_uvm
 
 #ifdef __NVCOMPILER_GPU_UNIFIED_MEM
diff --git a/src/simulation/m_data_output.fpp b/src/simulation/m_data_output.fpp
@@ -164,6 +164,7 @@ contains
 
     end subroutine s_open_probe_files
 
+    !> Open the immersed boundary state file for binary output
     impure subroutine s_open_ib_state_file
 
         character(len=path_len + 2*name_len) :: file_loc
@@ -1536,6 +1537,7 @@ contains
 
     end subroutine s_close_probe_files
 
+    !> Close the immersed boundary state file
     impure subroutine s_close_ib_state_file
 
         close (ib_state_unit)
diff --git a/src/simulation/m_global_parameters.fpp b/src/simulation/m_global_parameters.fpp
@@ -57,8 +57,7 @@ module m_global_parameters
     !> @{
     real(wp), target, allocatable, dimension(:) :: x_cc, y_cc, z_cc
     !> @}
-    ! type(bounds_info) :: x_domain, y_domain, z_domain !<
-    !! Locations of the domain bounds in the x-, y- and z-coordinate directions
+    ! type(bounds_info) :: x_domain, y_domain, z_domain !< Locations of the domain bounds in the x-, y- and z-coordinate directions
     !> @name Cell-width distributions in the x-, y- and z-directions, respectively
     !> @{
     real(wp), target, allocatable, dimension(:) :: dx, dy, dz
@@ -360,12 +359,9 @@ module m_global_parameters
     logical                                               :: ib
     integer                                               :: num_ibs
     logical                                               :: ib_state_wrt
-    type(ib_patch_parameters), dimension(num_patches_max) :: patch_ib
+    type(ib_patch_parameters), dimension(num_patches_max) :: patch_ib  !< Immersed boundary patch parameters
     type(vec3_dt), allocatable, dimension(:)              :: airfoil_grid_u, airfoil_grid_l
     integer                                               :: Np
-    !! Database of the immersed boundary patch parameters for each of the patches employed in the configuration of the initial
-    !! condition. Note that the maximum allowable number of patches, num_patches_max, may be changed in the module
-    !! m_derived_types.f90.
 
     $:GPU_DECLARE(create='[ib, num_ibs, patch_ib, Np, airfoil_grid_u, airfoil_grid_l]')
     !> @}
diff --git a/src/simulation/m_hyperelastic.fpp b/src/simulation/m_hyperelastic.fpp
@@ -17,8 +17,8 @@ module m_hyperelastic
 
     private; public :: s_hyperelastic_rmt_stress_update, s_initialize_hyperelastic_module, s_finalize_hyperelastic_module
 
-    !! The btensor at the cell-interior Gaussian quadrature points. These tensor is needed to be calculated once and make the code
-    !! DRY.
+    ! The btensor at the cell-interior Gaussian quadrature points. These tensor is needed to be calculated once and make the code
+    ! DRY.
     type(vector_field) :: btensor
     $:GPU_DECLARE(create='[btensor]')
 
diff --git a/src/simulation/m_ib_patches.fpp b/src/simulation/m_ib_patches.fpp
diff --git a/src/simulation/m_ibm.fpp b/src/simulation/m_ibm.fpp
diff --git a/src/simulation/m_muscl.fpp b/src/simulation/m_muscl.fpp
diff --git a/src/simulation/m_rhs.fpp b/src/simulation/m_rhs.fpp
diff --git a/src/simulation/m_riemann_solvers.fpp b/src/simulation/m_riemann_solvers.fpp
diff --git a/src/simulation/m_start_up.fpp b/src/simulation/m_start_up.fpp
diff --git a/src/simulation/m_surface_tension.fpp b/src/simulation/m_surface_tension.fpp
