docs(doxygen): 100% public-API coverage (228 → 0 undocumented)

Completes the work begun in the previous commit on this branch.  Every
public symbol under code/include/ now carries a brief Doxygen comment
(0 undocumented per scripts/doxygen-coverage.sh, with the `detail::`
implementation namespaces excluded as before).

Trajectory on this branch:
  start (after Doxyfile fix):  24.0 %  (165 / 437 in the no-detail set
                                       was 105 / 437 when detail counted)
  after PR #17 base commit  :  42.4 %  (165 / 396)
  this commit               : 100.0 %  (396 / 396)

Files touched (all .hpp / .h headers under code/include/):
  * cgal/Conformal_map_traits.h
  * clausen.hpp, conformal_mesh.hpp, constants.hpp (already docd)
  * cp_euclidean_functional.hpp, cut_graph.hpp, discrete_elliptic_utility.hpp
  * euclidean_functional.hpp, euclidean_geometry.hpp, euclidean_hessian.hpp
  * fundamental_domain.hpp, gauss_bonnet.hpp
  * hyper_ideal_{functional,geometry,hessian,utility,visualization_utility}.hpp
  * inversive_distance_functional.hpp, layout.hpp
  * matrix_utility.hpp, mesh_builder.hpp, mesh_io.hpp
  * newton_solver.hpp, p2_utility.hpp, period_matrix.hpp, projective_math.hpp
  * serialization.hpp, spherical_functional.hpp, spherical_geometry.hpp
  * spherical_hessian.hpp, viewer_utils.h

CI:
.gitea/workflows/doxygen-pages.yml now enforces
`scripts/doxygen-coverage.sh --threshold 100`, so any future regression
(a new public function landed without a `///` brief) fails the build
before the Doxygen HTML is published to Codeberg Pages.

Doxygen warnings remain at 0.

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

code/include/spherical_hessian.hpp

@@ -49,8 +49,18 @@ namespace conformallab {
 //   h2: edge v3-v1 → opposite v2 → w = cot(β2), β2=(π-α3-α1+α2)/2
 //
 // Returns valid=false if any β_k is out of range (degenerate face).
-struct SpherCotWeights { double w12, w23, w31; bool valid; };
+/// Three spherical "cotangent" weights for the three edges of a face,
+/// derived from the per-vertex interior angles `α₁, α₂, α₃` via
+/// `w_ij = cot(β_k)` with `β_k = (π − α_i − α_j + α_k) / 2`.
+struct SpherCotWeights {
+    double w12; ///< Weight for edge v₁-v₂ (opposite vertex v₃).
+    double w23; ///< Weight for edge v₂-v₃ (opposite vertex v₁).
+    double w31; ///< Weight for edge v₃-v₁ (opposite vertex v₂).
+    bool   valid; ///< `false` when any β_k is out of `(0, π/2]` (degenerate face).
+};
 
+/// Compute the three spherical cot weights from the three interior
+/// angles `(α₁, α₂, α₃)` of a spherical triangle.  See `SpherCotWeights`.
 inline SpherCotWeights spherical_cot_weights(double alpha1, double alpha2, double alpha3)
 {
     // β for each edge:
@@ -79,25 +89,10 @@ inline SpherCotWeights spherical_cot_weights(double alpha1, double alpha2, doubl
     return {1.0 / tb3, 1.0 / tb1, 1.0 / tb2, true};
 }
 
-// ── Analytical Hessian ────────────────────────────────────────────────────────
-//
-// Returns the n×n sparse Hessian matrix H where n = spherical_dimension(mesh, m).
-// x – current DOF vector.
-//
-// Derivation: G_v = θ_v − Σ_f α_v^f  →  H[i,j] = −Σ_f ∂α_i^f/∂u_j
-//
-// For a face (v1,v2,v3) with arc-lengths l12,l23,l31 and angles α1,α2,α3,
-// differentiating the spherical law of cosines
-//   cos(l_opp) = cos(l_a)cos(l_b) + sin(l_a)sin(l_b)cos(α)
-// gives:
-//   ∂α1/∂l12 = [cot(l12)cos(α1) − cot(l31)] / sin(α1)     (adjacent side)
-//   ∂α1/∂l31 = [cot(l31)cos(α1) − cot(l12)] / sin(α1)     (adjacent side)
-//   ∂α1/∂l23 = sin(l23) / [sin(l12)sin(l31)sin(α1)]        (opposite side)
-//
-// Chain rule with ∂l_ij/∂u_k = tan(l_ij/2)  (from l = 2·asin(exp(λ/2))):
-//   ∂α1/∂u1 = ∂α1/∂l12·t12 + ∂α1/∂l31·t31
-//   ∂α1/∂u2 = ∂α1/∂l12·t12 + ∂α1/∂l23·t23
-//   ∂α1/∂u3 = ∂α1/∂l23·t23 + ∂α1/∂l31·t31
+/// Analytical Spherical Hessian via `∂α/∂u` from the spherical law of
+/// cosines + chain rule `∂l/∂u = tan(l/2)`; returns an n×n sparse
+/// matrix with `n = spherical_dimension(mesh, m)`.  See block comment
+/// inside the body for the per-face derivation.
 inline Eigen::SparseMatrix<double> spherical_hessian(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -214,10 +209,8 @@ inline Eigen::SparseMatrix<double> spherical_hessian(
     return H;
 }
 
-// ── Finite-difference Hessian check ──────────────────────────────────────────
-//
-// Compares the analytical Hessian column-by-column against
-//   H_fd[:, j] = (G(x + ε·eⱼ) − G(x − ε·eⱼ)) / (2ε).
+/// FD Hessian check for the Spherical functional.  Compares analytic
+/// `H` column-by-column to `(G(x+εeⱼ) − G(x−εeⱼ)) / (2ε)`.
 inline bool hessian_check_spherical(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,