Fix Doxygen warnings across docs and Fortran sources (510 → 5)

- Remove filename args from @file directives in all 52 .fpp files
- Add @param docs to 13 undocumented subroutines, remove duplicate !< inline comments
- Convert raw $...$ math to Doxygen \f$...\f$ in m_riemann_solvers.fpp
- Add @cond/@endcond around #ifdef blocks that confuse Doxygen parser
- Fix getting-started.md HTML (<h3> in <summary>), contributing.md (@: escaping)
- Fix stale @param names in m_data_input.f90
- Remove obsolete Doxyfile tags (HTML_TIMESTAMP, LATEX_TIMESTAMP), fix PROJECT_NAME quoting
- Add stable {#id} anchors to generated case_constraints.md and cli-reference.md
- Add _escape_doxygen() helper for CLI help text, add missing precheck command
- Extend lint_docs.py with math syntax and section anchor checks

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

Author: sbryngelson

docs/Doxyfile.in

@@ -35,7 +35,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "@DOXYGEN_PROJECT_NAME@"
+PROJECT_NAME           = @DOXYGEN_PROJECT_NAME@
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -970,7 +970,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = readme.md
+USE_MDFILE_AS_MAINPAGE =
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1205,14 +1205,6 @@ HTML_COLORSTYLE_SAT    = 255
 
 HTML_COLORSTYLE_GAMMA  = 113
 
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting this
-# to YES can help to show when doxygen was last run and thus if the
-# documentation is up to date.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-HTML_TIMESTAMP         = NO
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that
@@ -1801,13 +1793,6 @@ LATEX_HIDE_INDICES     = NO
 
 LATEX_BIB_STYLE        = plain
 
-# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
-# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_TIMESTAMP        = NO
 
 # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
 # path from which the emoji images will be read. If a relative path is entered,

docs/documentation/case.md

@@ -148,7 +148,7 @@ Both human reviewers and AI code reviewers reference this section.
 ### Memory and Allocation
 
 - **ALLOCATE/DEALLOCATE pairing:** Every `@:ALLOCATE()` must have a matching `@:DEALLOCATE()`. Missing deallocations leak GPU memory.
-- **@:ACC_SETUP_VFs / @:ACC_SETUP_SFs:** Vector/scalar fields must have GPU pointer setup before use in kernels.
+- **`@:ACC_SETUP_VFs` / `@:ACC_SETUP_SFs`:** Vector/scalar fields must have GPU pointer setup before use in kernels.
 - **Conditional allocation:** If an array is allocated inside an `if` block, its deallocation must follow the same condition.
 - **Out-of-bounds access:** Fortran is permissive with assumed-shape arrays. Check that index arithmetic stays within declared bounds.
 

docs/documentation/contributing.md

@@ -70,7 +70,7 @@ for a Linux experience.
 
  <details>
 
-   <summary><h3>Windows + WSL (Recommended)</h3></summary>
+   <summary><b>Windows + WSL (Recommended)</b></summary>
 
 Install [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/) on Windows 11:
 Either
@@ -92,7 +92,7 @@ Once you have WSL installed, you can follow the instructions for *nix systems ab
 
   <details>
 
-   <summary><h3>Native Windows (Intel)</h3></summary>
+   <summary><b>Native Windows (Intel)</b></summary>
 
 Install the latest version of:
 - [Microsoft Visual Studio Community](https://visualstudio.microsoft.com/)
@@ -118,7 +118,9 @@ You will also have access to the `.sln` Microsoft Visual Studio solution files f
 
   </details>
 
-  <summary><h3>MacOS</h3></summary>
+  <details>
+
+  <summary><b>MacOS</b></summary>
 
 Using [Homebrew](https://brew.sh/) you can install the necessary dependencies
 before configuring your environment:

docs/documentation/getting-started.md

@@ -54,30 +54,30 @@ For analysis and processing of the database using VisIt's capability, the user i
 ## Serial data output
 
 If ``parallel_io = 'F'``, MFC will output the conservative variables to a directory `D/`. 
-If multiple cores are used ($\mathtt{ppn > 1}$), then a separate file is created for each core.
+If multiple cores are used (\f$\mathtt{ppn > 1}\f$), then a separate file is created for each core.
 If only one coordinate dimension (`n = 0` and `p = 0`) exists, the primitive variables will also be written to `D/`.
 The file names correspond to the variables associated with each equation solved by MFC.
 They are written at every `t_step_save` time step.
 The conservative variables are
 
-$$ {(\rho \alpha)}\_{1}, \dots, (\rho\alpha)\_{N\_c}, \rho u\_{1}, \dots, \rho u\_{N\_d}, E, \alpha\_1, \dots, \alpha\_{N\_c} $$
+\f[ (\rho \alpha)_{1}, \dots, (\rho\alpha)_{N_c}, \rho u_{1}, \dots, \rho u_{N_d}, E, \alpha_1, \dots, \alpha_{N_c} \f]
 
 and the primitive variables are
 
-$$ {(\rho \alpha)}\_1, \dots, (\rho\alpha)\_{N\_c}, u\_1, \dots, u\_{N\_d}, p, \alpha\_1, \dots, \alpha\_{N\_c} $$
+\f[ (\rho \alpha)_1, \dots, (\rho\alpha)_{N_c}, u_1, \dots, u_{N_d}, p, \alpha_1, \dots, \alpha_{N_c} \f]
 
 where $N_c$ are the number of components `num_fluids` and $N_d$ is the number of spatial dimensions. 
 There are exceptions: if `model_eqns = 3`, then the six-equation model appends these variables with the internal energies of each component.
 If there are sub-grid bubbles `bubbles = T`, then the bubble variables are also written. 
 These depend on the bubble dynamics model used.
 If ``polytropic = 'T'``, then the conservative variables are appended by 
 
-$$ n\_b R\_1, n\_b {\\dot R}\_1, \dots, n\_b R\_{N\_b}, n\_b {\\dot R}\_{N\_b} $$
+\f[ n_b R_1, n_b \dot{R}_1, \dots, n_b R_{N_b}, n_b \dot{R}_{N_b} \f]
 
 where $n_B$ is the bubble number density, and $N_b$ is the number of bubble sizes (see the matching variable in the input file, `Nb`).
 The primitive bubble variables do not include $n_B$:
 
-$$ R\_1, {\\dot R}\_1, \dots, R\_{N\_b}, {\\dot R}\_{N\_b} $$
+\f[ R_1, \dot{R}_1, \dots, R_{N_b}, \dot{R}_{N_b} \f]
 
 ## Remote Visualization on PACE Phoenix
 

docs/documentation/visualization.md

@@ -1,37 +1,37 @@
 #:def Hardcoded1DVariables()
-    ! Place any declaration of intermediate variables here
+    ! any declaration of intermediate variables here
     real(wp) :: x_mid_diffu, width_sq, profile_shape, temp, molar_mass_inv, y1, y2, y3, y4
 #:enddef
 
 #:def Hardcoded1D()
     select case (patch_icpp(patch_id)%hcid)
     case (150) ! 1D Smooth Alfven Case for MHD
-        ! velocity
+        !
         q_prim_vf(momxb + 1)%sf(i, 0, 0) = 0.1_wp*sin(2._wp*pi*x_cc(i))
         q_prim_vf(momxb + 2)%sf(i, 0, 0) = 0.1_wp*cos(2._wp*pi*x_cc(i))
 
-        ! magnetic field
+        ! field
         q_prim_vf(B_idx%end - 1)%sf(i, 0, 0) = 0.1_wp*sin(2._wp*pi*x_cc(i))
         q_prim_vf(B_idx%end)%sf(i, 0, 0) = 0.1_wp*cos(2._wp*pi*x_cc(i))
 
     case (170)
-        ! This hardcoded case can be used to start a simulation with initial conditions given from a known 1D profile (e.g. Cantera, SDtoolbox)
+        ! hardcoded case can be used to start a simulation with initial conditions given from a known 1D profile (e.g. Cantera, SDtoolbox)
         @: HardcodedReadValues()
 
     case (180)
-        ! This is patch is hard-coded for test suite optimization used in the
-        ! 1D_shuoser cases: "patch_icpp(2)%alpha_rho(1)": "1 + 0.2*sin(5*x)"
+        ! is patch is hard-coded for test suite optimization used in the
+        ! cases: "patch_icpp(2)%alpha_rho(1)": "1 + 0.2*sin(5*x)"
         if (patch_id == 2) then
             q_prim_vf(contxb + 0)%sf(i, 0, 0) = 1 + 0.2*sin(5*x_cc(i))
         end if
 
     case (181)
-        ! This is patch is hard-coded for test suite optimization used in the
-        ! 1D_titarevtorro cases: "patch_icpp(2)%alpha_rho(1)": "1 + 0.1*sin(20*x*pi)"
+        ! is patch is hard-coded for test suite optimization used in the
+        ! cases: "patch_icpp(2)%alpha_rho(1)": "1 + 0.1*sin(20*x*pi)"
         q_prim_vf(contxb + 0)%sf(i, 0, 0) = 1 + 0.1*sin(20*x_cc(i)*pi)
 
     case (182)
-        ! This patch is a hard-coded for test suite optimization (multiple component diffusion)
+        ! patch is a hard-coded for test suite optimization (multiple component diffusion)
         x_mid_diffu = 0.05_wp/2.0_wp
         width_sq = (2.5_wp*10.0_wp**(-3.0_wp))**2
         profile_shape = 1.0_wp - 0.5_wp*exp(-(x_cc(i) - x_mid_diffu)**2/width_sq)