From 443c75d55c8c8c5aaca98e35f1dbc77e269f8631 Mon Sep 17 00:00:00 2001
From: Daniel_Doehring <daniel.doehring@rwth-aachen.de>
Date: Mon, 30 Dec 2024 11:17:45 +0100
Subject: [PATCH] Docstrings for `flux_godunov` and `flux_ec`

---
 src/equations/hyperbolic_diffusion_2d.jl    |  6 ++++++
 src/equations/hyperbolic_diffusion_3d.jl    |  6 ++++++
 src/equations/inviscid_burgers_1d.jl        | 18 +++++++++++++++---
 src/equations/lattice_boltzmann_2d.jl       |  6 ++++++
 src/equations/lattice_boltzmann_3d.jl       |  6 ++++++
 src/equations/linear_scalar_advection_1d.jl |  9 +++++++--
 src/equations/linear_scalar_advection_2d.jl | 11 +++++++----
 src/equations/linear_scalar_advection_3d.jl | 11 +++++++----
 8 files changed, 60 insertions(+), 13 deletions(-)

diff --git a/src/equations/hyperbolic_diffusion_2d.jl b/src/equations/hyperbolic_diffusion_2d.jl
index 28f0c2bf47f..c324719c765 100644
--- a/src/equations/hyperbolic_diffusion_2d.jl
+++ b/src/equations/hyperbolic_diffusion_2d.jl
@@ -174,6 +174,12 @@ end
     sqrt(equations.nu * equations.inv_Tr) * norm(normal_direction)
 end
 
+"""
+    flux_godunov(u_ll, u_rr, orientation_or_normal_direction, 
+                 equations::HyperbolicDiffusionEquations2D)
+
+Godunov (upwind) flux for the hyperbolic diffusion equations.
+"""
 @inline function flux_godunov(u_ll, u_rr, orientation::Integer,
                               equations::HyperbolicDiffusionEquations2D)
     # Obtain left and right fluxes
diff --git a/src/equations/hyperbolic_diffusion_3d.jl b/src/equations/hyperbolic_diffusion_3d.jl
index e9017b1544e..657ee855ef1 100644
--- a/src/equations/hyperbolic_diffusion_3d.jl
+++ b/src/equations/hyperbolic_diffusion_3d.jl
@@ -188,6 +188,12 @@ end
     λ_max = sqrt(equations.nu * equations.inv_Tr)
 end
 
+"""
+    flux_godunov(u_ll, u_rr, orientation_or_normal_direction, 
+                 equations::HyperbolicDiffusionEquations3D)
+
+Godunov (upwind) flux for the hyperbolic diffusion equations.
+"""
 @inline function flux_godunov(u_ll, u_rr, orientation::Integer,
                               equations::HyperbolicDiffusionEquations3D)
     # Obtain left and right fluxes
diff --git a/src/equations/inviscid_burgers_1d.jl b/src/equations/inviscid_burgers_1d.jl
index afc6f9999c7..2f9d3d1f6f3 100644
--- a/src/equations/inviscid_burgers_1d.jl
+++ b/src/equations/inviscid_burgers_1d.jl
@@ -100,7 +100,14 @@ end
     return (abs(u[1]),)
 end
 
-# (Symmetric) Entropy Conserving flux
+@doc raw"""
+    flux_ec(u_ll, u_rr, orientation, equations::InviscidBurgersEquation1D)
+
+Entropy-conserving, symmetric flux for the inviscid Burgers' equation.
+```math
+F(u_L, u_R) = \frac{u_L^2 + u_L u_R + u_R^2}{6}
+```
+"""
 function flux_ec(u_ll, u_rr, orientation, equation::InviscidBurgersEquation1D)
     u_L = u_ll[1]
     u_R = u_rr[1]
@@ -108,8 +115,13 @@ function flux_ec(u_ll, u_rr, orientation, equation::InviscidBurgersEquation1D)
     return SVector((u_L^2 + u_L * u_R + u_R^2) / 6)
 end
 
-# See https://metaphor.ethz.ch/x/2019/hs/401-4671-00L/literature/mishra_hyperbolic_pdes.pdf ,
-# section 4.1.5 and especially equation (4.16).
+"""
+    flux_godunov(u_ll, u_rr, orientation, equations::InviscidBurgersEquation1D)
+
+Godunov (upwind) numerical flux for the inviscid Burgers' equation.
+See https://metaphor.ethz.ch/x/2019/hs/401-4671-00L/literature/mishra_hyperbolic_pdes.pdf ,
+section 4.1.5 and especially equation (4.16).
+"""
 function flux_godunov(u_ll, u_rr, orientation, equation::InviscidBurgersEquation1D)
     u_L = u_ll[1]
     u_R = u_rr[1]
diff --git a/src/equations/lattice_boltzmann_2d.jl b/src/equations/lattice_boltzmann_2d.jl
index 920f862f436..2693325bdc3 100644
--- a/src/equations/lattice_boltzmann_2d.jl
+++ b/src/equations/lattice_boltzmann_2d.jl
@@ -253,6 +253,12 @@ end
 #   λ_max =
 # end
 
+"""
+    flux_godunov(u_ll, u_rr, orientation, 
+                 equations::LatticeBoltzmannEquations2D)
+
+Godunov (upwind) flux for the Lattice-Boltzmann equations.
+"""
 @inline function flux_godunov(u_ll, u_rr, orientation::Integer,
                               equations::LatticeBoltzmannEquations2D)
     if orientation == 1
diff --git a/src/equations/lattice_boltzmann_3d.jl b/src/equations/lattice_boltzmann_3d.jl
index 1451eb7cbc1..0f4f60ee7ac 100644
--- a/src/equations/lattice_boltzmann_3d.jl
+++ b/src/equations/lattice_boltzmann_3d.jl
@@ -243,6 +243,12 @@ end
 #   λ_max =
 # end
 
+"""
+    flux_godunov(u_ll, u_rr, orientation, 
+                 equations::LatticeBoltzmannEquations3D)
+
+Godunov (upwind) flux for the Lattice-Boltzmann equations.
+"""
 @inline function flux_godunov(u_ll, u_rr, orientation::Integer,
                               equations::LatticeBoltzmannEquations3D)
     if orientation == 1 # x-direction
diff --git a/src/equations/linear_scalar_advection_1d.jl b/src/equations/linear_scalar_advection_1d.jl
index 743d2df870a..94a029971a7 100644
--- a/src/equations/linear_scalar_advection_1d.jl
+++ b/src/equations/linear_scalar_advection_1d.jl
@@ -141,8 +141,13 @@ end
     λ_max = abs(equation.advection_velocity[orientation])
 end
 
-# Essentially first order upwind, see e.g.
-# https://math.stackexchange.com/a/4355076/805029
+"""
+    flux_godunov(u_ll, u_rr, orientation, 
+                 equations::LinearScalarAdvectionEquation1D)
+
+Godunov (upwind) flux for the linear scalar advection equation.
+Essentially first order upwind, see e.g. https://math.stackexchange.com/a/4355076/805029 .
+"""
 function flux_godunov(u_ll, u_rr, orientation::Int,
                       equation::LinearScalarAdvectionEquation1D)
     u_L = u_ll[1]
diff --git a/src/equations/linear_scalar_advection_2d.jl b/src/equations/linear_scalar_advection_2d.jl
index 5e4f8463f52..79ae2a6308a 100644
--- a/src/equations/linear_scalar_advection_2d.jl
+++ b/src/equations/linear_scalar_advection_2d.jl
@@ -239,8 +239,13 @@ end
     return abs(a)
 end
 
-# Essentially first order upwind, see e.g.
-# https://math.stackexchange.com/a/4355076/805029
+"""
+    flux_godunov(u_ll, u_rr, orientation_or_normal_direction, 
+                 equations::LinearScalarAdvectionEquation2D)
+
+Godunov (upwind) flux for the linear scalar advection equation.
+Essentially first order upwind, see e.g. https://math.stackexchange.com/a/4355076/805029 .
+"""
 function flux_godunov(u_ll, u_rr, orientation::Integer,
                       equation::LinearScalarAdvectionEquation2D)
     u_L = u_ll[1]
@@ -254,8 +259,6 @@ function flux_godunov(u_ll, u_rr, orientation::Integer,
     end
 end
 
-# Essentially first order upwind, see e.g.
-# https://math.stackexchange.com/a/4355076/805029
 function flux_godunov(u_ll, u_rr, normal_direction::AbstractVector,
                       equation::LinearScalarAdvectionEquation2D)
     u_L = u_ll[1]
diff --git a/src/equations/linear_scalar_advection_3d.jl b/src/equations/linear_scalar_advection_3d.jl
index 088f934cc3e..6463b060493 100644
--- a/src/equations/linear_scalar_advection_3d.jl
+++ b/src/equations/linear_scalar_advection_3d.jl
@@ -158,8 +158,13 @@ end
     return abs(a)
 end
 
-# Essentially first order upwind, see e.g.
-# https://math.stackexchange.com/a/4355076/805029
+"""
+    flux_godunov(u_ll, u_rr, orientation_or_normal_direction, 
+                 equations::LinearScalarAdvectionEquation3D)
+
+Godunov (upwind) flux for the linear scalar advection equation.
+Essentially first order upwind, see e.g. https://math.stackexchange.com/a/4355076/805029 .
+"""
 function flux_godunov(u_ll, u_rr, orientation::Integer,
                       equation::LinearScalarAdvectionEquation3D)
     u_L = u_ll[1]
@@ -173,8 +178,6 @@ function flux_godunov(u_ll, u_rr, orientation::Integer,
     end
 end
 
-# Essentially first order upwind, see e.g.
-# https://math.stackexchange.com/a/4355076/805029
 function flux_godunov(u_ll, u_rr, normal_direction::AbstractVector,
                       equation::LinearScalarAdvectionEquation3D)
     u_L = u_ll[1]