Add subroutine @brief descriptions and sidebar cross-navigation

- Add ~170 !> @brief one-line descriptions to previously undocumented
  subroutines/functions across all 45 source files
- Add cross-navigation links (User Guide, Pre-Process/Simulation/Post-
  Process API) injected at the top of the Doxygen sidebar via JavaScript
- Fix stale @param ib in s_ib_3D_airfoil

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

docs/custom.css

@@ -3,6 +3,38 @@
  * Overrides for doxygen-awesome theme
  */
 
+/* Cross-navigation panel at top of sidebar */
+#mfc-nav {
+    display: flex;
+    flex-direction: column;
+    padding: 10px 12px 8px;
+    border-bottom: 1px solid var(--separator-color);
+    background: var(--side-nav-background);
+    font-size: 0.8rem;
+}
+
+#mfc-nav a {
+    display: block;
+    padding: 4px 8px;
+    border-radius: 4px;
+    color: var(--page-foreground-color);
+    text-decoration: none;
+    opacity: 0.75;
+    transition: background 0.12s, opacity 0.12s;
+}
+
+#mfc-nav a:hover {
+    opacity: 1;
+    background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
+}
+
+#mfc-nav a.active {
+    font-weight: 600;
+    opacity: 1;
+    color: var(--primary-color);
+    background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
+}
+
 /* Narrower left navigation panel */
 html {
     --side-nav-fixed-width: 210px;

docs/header.html

@@ -66,4 +66,27 @@
 </table>
 </div>
 <!--END TITLEAREA-->
+<!-- Cross-navigation injected into sidebar via script below -->
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+  var nav = document.createElement('div');
+  nav.id = 'mfc-nav';
+  var items = [
+    ['../documentation/index.html', 'documentation', 'User Guide'],
+    ['../pre_process/index.html',   'pre_process',   'Pre-Process API'],
+    ['../simulation/index.html',    'simulation',    'Simulation API'],
+    ['../post_process/index.html',  'post_process',  'Post-Process API']
+  ];
+  var path = window.location.pathname;
+  for (var i = 0; i < items.length; i++) {
+    var a = document.createElement('a');
+    a.href = items[i][0];
+    a.textContent = items[i][2];
+    if (path.indexOf('/' + items[i][1] + '/') !== -1) a.className = 'active';
+    nav.appendChild(a);
+  }
+  var sideNav = document.getElementById('side-nav');
+  if (sideNav) sideNav.insertBefore(nav, sideNav.firstChild);
+});
+</script>
 <!-- end header part -->

src/common/m_boundary_common.fpp

@@ -52,6 +52,7 @@ module m_boundary_common
 
 contains
 
+    !> @brief Allocates and sets up boundary condition buffer arrays for all coordinate directions.
     impure subroutine s_initialize_boundary_common_module()
 
         integer :: i, j
@@ -296,6 +297,7 @@ contains
 
     end subroutine s_populate_variables_buffers
 
+    !> @brief Fills ghost cells by copying the nearest boundary cell value along the specified direction.
     subroutine s_ghost_cell_extrapolation(q_prim_vf, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_ghost_cell_extrapolation', &
             & parallelism='[seq]', cray_inline=True)
@@ -357,6 +359,7 @@ contains
 
     end subroutine s_ghost_cell_extrapolation
 
+    !> @brief Applies reflective (symmetry) boundary conditions by mirroring primitive variables and flipping the normal velocity component.
     subroutine s_symmetry(q_prim_vf, bc_dir, bc_loc, k, l, pb_in, mv_in)
         $:GPU_ROUTINE(parallelism='[seq]')
         type(scalar_field), dimension(sys_size), intent(inout) :: q_prim_vf
@@ -617,6 +620,7 @@ contains
 
     end subroutine s_symmetry
 
+    !> @brief Applies periodic boundary conditions by copying values from the opposite domain boundary.
     subroutine s_periodic(q_prim_vf, bc_dir, bc_loc, k, l, pb_in, mv_in)
         $:GPU_ROUTINE(parallelism='[seq]')
         type(scalar_field), dimension(sys_size), intent(inout) :: q_prim_vf
@@ -756,6 +760,7 @@ contains
 
     end subroutine s_periodic
 
+    !> @brief Applies axis boundary conditions for cylindrical coordinates by reflecting values across the axis with azimuthal phase shift.
     subroutine s_axis(q_prim_vf, pb_in, mv_in, k, l)
         $:GPU_ROUTINE(parallelism='[seq]')
         type(scalar_field), dimension(sys_size), intent(inout) :: q_prim_vf
@@ -815,6 +820,7 @@ contains
 
     end subroutine s_axis
 
+    !> @brief Applies slip wall boundary conditions by extrapolating scalars and reflecting the wall-normal velocity component.
     subroutine s_slip_wall(q_prim_vf, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_slip_wall',parallelism='[seq]', &
             & cray_inline=True)
@@ -906,6 +912,7 @@ contains
 
     end subroutine s_slip_wall
 
+    !> @brief Applies no-slip wall boundary conditions by reflecting and negating all velocity components at the wall.
     subroutine s_no_slip_wall(q_prim_vf, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_no_slip_wall',parallelism='[seq]', &
             & cray_inline=True)
@@ -1034,6 +1041,7 @@ contains
 
     end subroutine s_no_slip_wall
 
+    !> @brief Applies Dirichlet boundary conditions by prescribing ghost cell values from stored boundary buffers.
     subroutine s_dirichlet(q_prim_vf, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_dirichlet',parallelism='[seq]', &
             & cray_inline=True)
@@ -1103,6 +1111,7 @@ contains
 
     end subroutine s_dirichlet
 
+    !> @brief Extrapolates QBMM bubble pressure and mass-vapor variables into ghost cells by copying boundary values.
     subroutine s_qbmm_extrapolation(bc_dir, bc_loc, k, l, pb_in, mv_in)
         $:GPU_ROUTINE(parallelism='[seq]')
         real(stp), optional, dimension(idwbuff(1)%beg:, idwbuff(2)%beg:, idwbuff(3)%beg:, 1:, 1:), intent(inout) :: pb_in, mv_in
@@ -1175,6 +1184,7 @@ contains
 
     end subroutine s_qbmm_extrapolation
 
+    !> @brief Populates ghost cell buffers for the color function and its divergence used in capillary surface tension.
     impure subroutine s_populate_capillary_buffers(c_divs, bc_type)
 
         type(scalar_field), dimension(num_dims + 1), intent(inout) :: c_divs
@@ -1310,6 +1320,7 @@ contains
         #:endif
     end subroutine s_populate_capillary_buffers
 
+    !> @brief Applies periodic boundary conditions to the color function and its divergence fields.
     subroutine s_color_function_periodic(c_divs, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_color_function_periodic', &
             & parallelism='[seq]', cray_inline=True)
@@ -1365,6 +1376,7 @@ contains
 
     end subroutine s_color_function_periodic
 
+    !> @brief Applies reflective boundary conditions to the color function and its divergence fields.
     subroutine s_color_function_reflective(c_divs, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_color_function_reflective', &
             & parallelism='[seq]', cray_inline=True)
@@ -1444,6 +1456,7 @@ contains
 
     end subroutine s_color_function_reflective
 
+    !> @brief Extrapolates the color function and its divergence into ghost cells by copying boundary values.
     subroutine s_color_function_ghost_cell_extrapolation(c_divs, bc_dir, bc_loc, k, l)
         $:GPU_ROUTINE(function_name='s_color_function_ghost_cell_extrapolation', &
             & parallelism='[seq]', cray_inline=True)
@@ -1499,6 +1512,7 @@ contains
 
     end subroutine s_color_function_ghost_cell_extrapolation
 
+    !> @brief Populates ghost cell buffers for the Jacobian scalar field used in the IGR elliptic solver.
     impure subroutine s_populate_F_igr_buffers(bc_type, jac_sf)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -1670,6 +1684,7 @@ contains
         #:endif
     end subroutine s_populate_F_igr_buffers
 
+    !> @brief Creates MPI derived datatypes for boundary condition type arrays and buffer arrays used in parallel I/O.
     impure subroutine s_create_mpi_types(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -1703,6 +1718,7 @@ contains
 #endif
     end subroutine s_create_mpi_types
 
+    !> @brief Writes boundary condition type and buffer data to serial (unformatted) restart files.
     subroutine s_write_serial_boundary_condition_files(q_prim_vf, bc_type, step_dirpath, old_grid_in)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_prim_vf
@@ -1744,6 +1760,7 @@ contains
 
     end subroutine s_write_serial_boundary_condition_files
 
+    !> @brief Writes boundary condition type and buffer data to per-rank parallel files using MPI I/O.
     subroutine s_write_parallel_boundary_condition_files(q_prim_vf, bc_type)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_prim_vf
@@ -1810,6 +1827,7 @@ contains
 
     end subroutine s_write_parallel_boundary_condition_files
 
+    !> @brief Reads boundary condition type and buffer data from serial (unformatted) restart files.
     subroutine s_read_serial_boundary_condition_files(step_dirpath, bc_type)
 
         character(LEN=*), intent(in) :: step_dirpath
@@ -1856,6 +1874,7 @@ contains
 
     end subroutine s_read_serial_boundary_condition_files
 
+    !> @brief Reads boundary condition type and buffer data from per-rank parallel files using MPI I/O.
     subroutine s_read_parallel_boundary_condition_files(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(inout) :: bc_type
@@ -1922,6 +1941,7 @@ contains
 
     end subroutine s_read_parallel_boundary_condition_files
 
+    !> @brief Packs primitive variable boundary slices into bc_buffers arrays for serialization.
     subroutine s_pack_boundary_condition_buffers(q_prim_vf)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_prim_vf
@@ -1968,6 +1988,7 @@ contains
 
     end subroutine s_pack_boundary_condition_buffers
 
+    !> @brief Initializes the per-cell boundary condition type arrays with the global default BC values.
     subroutine s_assign_default_bc_type(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -2183,6 +2204,7 @@ contains
 
     end subroutine s_populate_grid_variables_buffers
 
+    !> @brief Deallocates boundary condition buffer arrays allocated during module initialization.
     subroutine s_finalize_boundary_common_module()
 
         if (bc_io) then

src/common/m_checker_common.fpp

@@ -38,6 +38,7 @@ contains
 
 #ifndef MFC_SIMULATION
 
+    !> @brief Verifies that the total number of grid cells meets the minimum required by the number of dimensions and MPI ranks.
     impure subroutine s_check_total_cells
         character(len=18) :: numStr !< for int to string conversion
         integer(kind=8) :: min_cells
@@ -52,6 +53,7 @@ contains
 
 #endif
 
+    !> @brief Checks that simulation parameters stay within AMD GPU compiler limits when case optimization is disabled.
     impure subroutine s_check_amd
 
         #:if not MFC_CASE_OPTIMIZATION

src/common/m_chemistry.fpp

@@ -34,6 +34,7 @@ module m_chemistry
 
 contains
 
+    !> @brief Computes mixture viscosities for left and right states and inverts them for use as reciprocal Reynolds numbers.
     subroutine compute_viscosity_and_inversion(T_L, Ys_L, T_R, Ys_R, Re_L, Re_R)
 
         $:GPU_ROUTINE(function_name='compute_viscosity_and_inversion',parallelism='[seq]', &
@@ -49,6 +50,7 @@ contains
 
     end subroutine compute_viscosity_and_inversion
 
+    !> @brief Initializes the temperature field from conservative variables by inverting the energy equation.
     subroutine s_compute_q_T_sf(q_T_sf, q_cons_vf, bounds)
 
         ! Initialize the temperature field at the start of the simulation to
@@ -91,6 +93,7 @@ contains
 
     end subroutine s_compute_q_T_sf
 
+    !> @brief Computes the temperature field from primitive variables using the ideal gas law and mixture molecular weight.
     subroutine s_compute_T_from_primitives(q_T_sf, q_prim_vf, bounds)
 
         type(scalar_field), intent(inout) :: q_T_sf
@@ -116,6 +119,7 @@ contains
 
     end subroutine s_compute_T_from_primitives
 
+    !> @brief Adds chemical reaction source terms to the species transport RHS using net production rates.
     subroutine s_compute_chemistry_reaction_flux(rhs_vf, q_cons_qp, q_T_sf, q_prim_qp, bounds)
 
         type(scalar_field), dimension(sys_size), intent(inout) :: rhs_vf
@@ -168,6 +172,7 @@ contains
 
     end subroutine s_compute_chemistry_reaction_flux
 
+    !> @brief Computes species mass diffusion fluxes at cell interfaces using mixture-averaged diffusivities.
     subroutine s_compute_chemistry_diffusion_flux(idir, q_prim_qp, flux_src_vf, irx, iry, irz)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_prim_qp

src/common/m_compile_specific.f90

@@ -25,6 +25,7 @@ impure subroutine s_create_directory(dir_name)
 
     end subroutine s_create_directory
 
+    !> @brief Deletes a file at the given path using a platform-specific system command.
     impure subroutine s_delete_file(filepath)
         character(LEN=*), intent(in) :: filepath
 
@@ -36,6 +37,7 @@ impure subroutine s_delete_file(filepath)
 
     end subroutine s_delete_file
 
+    !> @brief Recursively deletes a directory using a platform-specific system command.
     impure subroutine s_delete_directory(dir_name)
         character(LEN=*), intent(in) :: dir_name
 
@@ -62,12 +64,14 @@ impure subroutine my_inquire(fileloc, dircheck)
 
     end subroutine my_inquire
 
+    !> @brief Retrieves the current working directory path via the GETCWD intrinsic.
     impure subroutine s_get_cwd(cwd)
         character(LEN=*), intent(out) :: cwd
 
         call GETCWD(cwd)
     end subroutine s_get_cwd
 
+    !> @brief Extracts the base filename from a directory path using the system basename command.
     impure subroutine s_get_basename(dirpath, basename)
         character(LEN=*), intent(in) :: dirpath
         character(LEN=*), intent(out) :: basename

src/common/m_delay_file_access.f90

@@ -16,6 +16,7 @@ module m_delay_file_access
 
 contains
 
+    !> @brief Introduces a rank-dependent busy-wait delay to stagger parallel file access and reduce I/O contention.
     impure subroutine DelayFileAccess(ProcessRank)
         integer, intent(in) :: ProcessRank
 

src/common/m_helper.fpp

@@ -65,6 +65,7 @@ contains
 
     end subroutine s_comp_n_from_prim
 
+    !> @brief Computes the bubble number density from the conservative void fraction and weighted bubble radii.
     subroutine s_comp_n_from_cons(vftmp, nRtmp, ntmp, weights)
         $:GPU_ROUTINE(parallelism='[seq]')
         real(wp), intent(in) :: vftmp
@@ -79,6 +80,7 @@ contains
 
     end subroutine s_comp_n_from_cons
 
+    !> @brief Prints a 2D real array to standard output, optionally dividing each element by a given scalar.
     impure subroutine s_print_2D_array(A, div)
 
         real(wp), dimension(:, :), intent(in) :: A
@@ -274,6 +276,7 @@ contains
 
     end subroutine s_transcoeff
 
+    !> @brief Converts an integer to its trimmed string representation.
     elemental subroutine s_int_to_str(i, res)
 
         integer, intent(in) :: i
@@ -664,6 +667,7 @@ contains
 
     end function f_gx
 
+    !> @brief Downsamples conservative variable fields by a factor of 3 in each direction using volume averaging.
     subroutine s_downsample_data(q_cons_vf, q_cons_temp, m_ds, n_ds, p_ds, m_glb_ds, n_glb_ds, p_glb_ds)
 
         type(scalar_field), dimension(sys_size), intent(inout) :: q_cons_vf, q_cons_temp
@@ -705,6 +709,7 @@ contains
 
     end subroutine s_downsample_data
 
+    !> @brief Upsamples conservative variable fields from a coarsened grid back to the original resolution using interpolation.
     subroutine s_upsample_data(q_cons_vf, q_cons_temp)
 
         type(scalar_field), intent(inout), dimension(sys_size) :: q_cons_vf, q_cons_temp

src/common/m_model.fpp

@@ -462,6 +462,7 @@ contains
 
     end function f_read_line
 
+    !> @brief Reads the next non-comment line from a model file, using a buffered look-ahead mechanism.
     impure subroutine s_skip_ignored_lines(iunit, buffered_line, is_buffered)
         integer, intent(in) :: iunit
         character(80), intent(inout) :: buffered_line