Rewrite module briefs, add description tables to landing pages, and lint for missing briefs

- Rewrite ~51 module-level !> @brief descriptions to be concise and
  descriptive (one sentence, no boilerplate)
- Update gen_api_landing.py to extract briefs from source files and
  render module tables with descriptions on API landing pages
- Add check_module_briefs() linter to lint_docs.py ensuring every
  m_*.fpp/.f90 has a module-level !> @brief before the module declaration

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

Author: sbryngelson

docs/gen_api_landing.py

@@ -10,11 +10,14 @@
 
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 
 src_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
 
+_BRIEF_RE = re.compile(r"^!>\s*@brief\s+(.+)", re.IGNORECASE)
+
 TARGETS = {
     "pre_process": {
         "title": "MFC Pre-Process",
@@ -47,13 +50,60 @@
 }
 
 
-def get_modules(directory: Path) -> list[str]:
-    """Return sorted list of module names (m_*) from .fpp and .f90 files."""
-    modules: set[str] = set()
+def _extract_brief(path: Path) -> str:
+    """Extract the module-level @brief from a Fortran source file.
+
+    Reads the first !> @brief line (outside the @file block) and any
+    !! continuation lines, joins them, and returns the first sentence.
+    """
+    lines = path.read_text(encoding="utf-8").splitlines()
+    parts: list[str] = []
+    in_file_block = False
+    collecting = False
+    for line in lines[:40]:
+        stripped = line.strip()
+        # Track whether we are inside the @file doc-comment block
+        if stripped.startswith("!>") and not stripped.startswith("!> @brief"):
+            in_file_block = True
+            continue
+        if in_file_block and stripped.startswith("!!"):
+            continue
+        if in_file_block:
+            in_file_block = False
+        # Match module-level @brief (outside @file block)
+        m = _BRIEF_RE.match(stripped)
+        if m and not collecting:
+            brief_text = m.group(1).strip()
+            # Skip file-level "Contains module/program X" briefs
+            if re.match(r"Contains\s+(module|program)\s+\w+", brief_text):
+                continue
+            parts.append(brief_text)
+            collecting = True
+            continue
+        if collecting:
+            if stripped.startswith("!!"):
+                parts.append(stripped.lstrip("! ").strip())
+            else:
+                break
+    if not parts:
+        return ""
+    text = " ".join(parts)
+    # Take first sentence only
+    dot = text.find(". ")
+    if dot != -1:
+        text = text[:dot]
+    return text.rstrip(". ").strip()
+
+
+def get_modules(directory: Path) -> list[tuple[str, str]]:
+    """Return sorted list of (module_name, brief) from .fpp and .f90 files."""
+    modules: dict[str, str] = {}
     for pattern in ("m_*.fpp", "m_*.f90"):
         for f in directory.glob(pattern):
-            modules.add(f.stem)
-    return sorted(modules)
+            if f.stem in modules:
+                continue
+            modules[f.stem] = _extract_brief(f)
+    return sorted(modules.items())
 
 
 for target, info in TARGETS.items():
@@ -74,15 +124,19 @@ def get_modules(directory: Path) -> list[str]:
     if target_modules:
         lines.append(f"### {info['title'].split()[-1]}")
         lines.append("")
-        for m in target_modules:
-            lines.append(f"- @ref {m.lower()} \"{m}\"")
+        lines.append("| Module | Description |")
+        lines.append("|--------|-------------|")
+        for name, brief in target_modules:
+            lines.append(f"| @ref {name.lower()} \"{name}\" | {brief} |")
         lines.append("")
 
     if common_modules:
         lines.append("### Common (shared)")
         lines.append("")
-        for m in common_modules:
-            lines.append(f"- @ref {m.lower()} \"{m}\"")
+        lines.append("| Module | Description |")
+        lines.append("|--------|-------------|")
+        for name, brief in common_modules:
+            lines.append(f"| @ref {name.lower()} \"{name}\" | {brief} |")
         lines.append("")
 
     lines.append("## See Also")

docs/post_process/readme.md

@@ -6,32 +6,36 @@ The post-process component reads raw simulation output and computes derived quan
 
 ### Post-Process
 
-- @ref m_checker "m_checker"
-- @ref m_data_input "m_data_input"
-- @ref m_data_output "m_data_output"
-- @ref m_derived_variables "m_derived_variables"
-- @ref m_global_parameters "m_global_parameters"
-- @ref m_mpi_proxy "m_mpi_proxy"
-- @ref m_start_up "m_start_up"
+| Module | Description |
+|--------|-------------|
+| @ref m_checker "m_checker" | Validates post-process input parameters and output format consistency |
+| @ref m_data_input "m_data_input" | Reads raw simulation grid and conservative-variable data for a given time-step and fills buffer regions |
+| @ref m_data_output "m_data_output" | Writes post-processed grid and flow-variable data to Silo-HDF5 or binary database files |
+| @ref m_derived_variables "m_derived_variables" | Computes derived flow quantities (sound speed, vorticity, Schlieren, etc.) from conservative and primitive variables |
+| @ref m_global_parameters "m_global_parameters" | Global parameters for the post-process: domain geometry, equation of state, and output database settings |
+| @ref m_mpi_proxy "m_mpi_proxy" | MPI gather and scatter operations for distributing post-process grid and flow-variable data |
+| @ref m_start_up "m_start_up" | Reads and validates user inputs, allocates variables, and configures MPI decomposition and I/O for post-processing |
 
 ### Common (shared)
 
-- @ref m_boundary_common "m_boundary_common"
-- @ref m_checker_common "m_checker_common"
-- @ref m_chemistry "m_chemistry"
-- @ref m_compile_specific "m_compile_specific"
-- @ref m_constants "m_constants"
-- @ref m_delay_file_access "m_delay_file_access"
-- @ref m_derived_types "m_derived_types"
-- @ref m_finite_differences "m_finite_differences"
-- @ref m_helper "m_helper"
-- @ref m_helper_basic "m_helper_basic"
-- @ref m_model "m_model"
-- @ref m_mpi_common "m_mpi_common"
-- @ref m_nvtx "m_nvtx"
-- @ref m_phase_change "m_phase_change"
-- @ref m_precision_select "m_precision_select"
-- @ref m_variables_conversion "m_variables_conversion"
+| Module | Description |
+|--------|-------------|
+| @ref m_boundary_common "m_boundary_common" | Noncharacteristic and processor boundary condition application for ghost cells and buffer regions |
+| @ref m_checker_common "m_checker_common" | Shared input validation checks for grid dimensions and AMD GPU compiler limits |
+| @ref m_chemistry "m_chemistry" | Multi-species chemistry interface for thermodynamic properties, reaction rates, and transport coefficients |
+| @ref m_compile_specific "m_compile_specific" | Platform-specific file and directory operations: create, delete, inquire, getcwd, and basename |
+| @ref m_constants "m_constants" | Compile-time constant parameters: default values, tolerances, and physical constants |
+| @ref m_delay_file_access "m_delay_file_access" | Rank-staggered file access delays to prevent I/O contention on parallel file systems |
+| @ref m_derived_types "m_derived_types" | Shared derived types for field data, patch geometry, bubble dynamics, and MPI I/O structures |
+| @ref m_finite_differences "m_finite_differences" | Finite difference operators for computing divergence of velocity fields |
+| @ref m_helper "m_helper" | Utility routines for bubble model setup, coordinate transforms, array sampling, and special functions |
+| @ref m_helper_basic "m_helper_basic" | Basic floating-point utilities: approximate equality, default detection, and coordinate bounds |
+| @ref m_model "m_model" | Binary STL file reader and processor for immersed boundary geometry |
+| @ref m_mpi_common "m_mpi_common" | MPI communication layer: domain decomposition, halo exchange, reductions, and parallel I/O setup |
+| @ref m_nvtx "m_nvtx" | NVIDIA NVTX profiling API bindings for GPU performance instrumentation |
+| @ref m_phase_change "m_phase_change" | Phase transition relaxation solvers for liquid-vapor flows with cavitation and boiling |
+| @ref m_precision_select "m_precision_select" | Working-precision kind selection (half/single/double) and corresponding MPI datatype parameters |
+| @ref m_variables_conversion "m_variables_conversion" | Conservative-to-primitive variable conversion, mixture property evaluation, and pressure computation |
 
 ## See Also
 

docs/pre_process/readme.md

@@ -6,39 +6,43 @@ The pre-process component generates initial conditions and computational meshes
 
 ### Pre-Process
 
-- @ref m_assign_variables "m_assign_variables"
-- @ref m_boundary_conditions "m_boundary_conditions"
-- @ref m_check_ib_patches "m_check_ib_patches"
-- @ref m_check_patches "m_check_patches"
-- @ref m_checker "m_checker"
-- @ref m_data_output "m_data_output"
-- @ref m_global_parameters "m_global_parameters"
-- @ref m_grid "m_grid"
-- @ref m_icpp_patches "m_icpp_patches"
-- @ref m_initial_condition "m_initial_condition"
-- @ref m_mpi_proxy "m_mpi_proxy"
-- @ref m_perturbation "m_perturbation"
-- @ref m_simplex_noise "m_simplex_noise"
-- @ref m_start_up "m_start_up"
+| Module | Description |
+|--------|-------------|
+| @ref m_assign_variables "m_assign_variables" | Assigns initial primitive variables to computational cells based on patch geometry |
+| @ref m_boundary_conditions "m_boundary_conditions" | Applies spatially varying boundary condition patches along domain edges and faces |
+| @ref m_check_ib_patches "m_check_ib_patches" | Validates geometry parameters and constraints for immersed boundary patches |
+| @ref m_check_patches "m_check_patches" | Validates geometry parameters and constraints for initial condition patches |
+| @ref m_checker "m_checker" | Checks pre-process input file parameters for compatibility and correctness |
+| @ref m_data_output "m_data_output" | Writes grid and initial condition data to serial or parallel output files |
+| @ref m_global_parameters "m_global_parameters" | Defines global parameters for the computational domain, simulation algorithm, and initial conditions |
+| @ref m_grid "m_grid" | Generates uniform or stretched rectilinear grids with hyperbolic-tangent spacing |
+| @ref m_icpp_patches "m_icpp_patches" | Constructs initial condition patch geometries (lines, circles, rectangles, spheres, etc.) on the grid |
+| @ref m_initial_condition "m_initial_condition" | Assembles initial conditions by layering prioritized patches via constructive solid geometry |
+| @ref m_mpi_proxy "m_mpi_proxy" | Broadcasts user inputs and decomposes the domain across MPI ranks for pre-processing |
+| @ref m_perturbation "m_perturbation" | Perturbs initial mean flow fields with random noise, mixing-layer instabilities, or simplex noise |
+| @ref m_simplex_noise "m_simplex_noise" | 2D and 3D simplex noise generation for procedural initial condition perturbations |
+| @ref m_start_up "m_start_up" | Reads and validates user inputs, loads existing grid/IC data, and initializes pre-process modules |
 
 ### Common (shared)
 
-- @ref m_boundary_common "m_boundary_common"
-- @ref m_checker_common "m_checker_common"
-- @ref m_chemistry "m_chemistry"
-- @ref m_compile_specific "m_compile_specific"
-- @ref m_constants "m_constants"
-- @ref m_delay_file_access "m_delay_file_access"
-- @ref m_derived_types "m_derived_types"
-- @ref m_finite_differences "m_finite_differences"
-- @ref m_helper "m_helper"
-- @ref m_helper_basic "m_helper_basic"
-- @ref m_model "m_model"
-- @ref m_mpi_common "m_mpi_common"
-- @ref m_nvtx "m_nvtx"
-- @ref m_phase_change "m_phase_change"
-- @ref m_precision_select "m_precision_select"
-- @ref m_variables_conversion "m_variables_conversion"
+| Module | Description |
+|--------|-------------|
+| @ref m_boundary_common "m_boundary_common" | Noncharacteristic and processor boundary condition application for ghost cells and buffer regions |
+| @ref m_checker_common "m_checker_common" | Shared input validation checks for grid dimensions and AMD GPU compiler limits |
+| @ref m_chemistry "m_chemistry" | Multi-species chemistry interface for thermodynamic properties, reaction rates, and transport coefficients |
+| @ref m_compile_specific "m_compile_specific" | Platform-specific file and directory operations: create, delete, inquire, getcwd, and basename |
+| @ref m_constants "m_constants" | Compile-time constant parameters: default values, tolerances, and physical constants |
+| @ref m_delay_file_access "m_delay_file_access" | Rank-staggered file access delays to prevent I/O contention on parallel file systems |
+| @ref m_derived_types "m_derived_types" | Shared derived types for field data, patch geometry, bubble dynamics, and MPI I/O structures |
+| @ref m_finite_differences "m_finite_differences" | Finite difference operators for computing divergence of velocity fields |
+| @ref m_helper "m_helper" | Utility routines for bubble model setup, coordinate transforms, array sampling, and special functions |
+| @ref m_helper_basic "m_helper_basic" | Basic floating-point utilities: approximate equality, default detection, and coordinate bounds |
+| @ref m_model "m_model" | Binary STL file reader and processor for immersed boundary geometry |
+| @ref m_mpi_common "m_mpi_common" | MPI communication layer: domain decomposition, halo exchange, reductions, and parallel I/O setup |
+| @ref m_nvtx "m_nvtx" | NVIDIA NVTX profiling API bindings for GPU performance instrumentation |
+| @ref m_phase_change "m_phase_change" | Phase transition relaxation solvers for liquid-vapor flows with cavitation and boiling |
+| @ref m_precision_select "m_precision_select" | Working-precision kind selection (half/single/double) and corresponding MPI datatype parameters |
+| @ref m_variables_conversion "m_variables_conversion" | Conservative-to-primitive variable conversion, mixture property evaluation, and pressure computation |
 
 ## See Also