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/cp_euclidean_functional.hpp

@@ -77,12 +77,17 @@ namespace conformallab {
 
 // ── Property-map type aliases ────────────────────────────────────────────────
 
+/// Property map face → `int`    for the CP-Euclidean functional.
 using CPFMapI = ConformalMesh::Property_map<Face_index, int>;
+/// Property map face → `double` for the CP-Euclidean functional.
 using CPFMapD = ConformalMesh::Property_map<Face_index, double>;
+/// Property map edge → `double` for the CP-Euclidean functional.
 using CPEMapD = ConformalMesh::Property_map<Edge_index, double>;
 
 // ── Persistent map bundle ─────────────────────────────────────────────────────
 
+/// Bundle of the three property maps consumed by the CP-Euclidean
+/// (Bobenko-Pinkall-Springborn 2010) circle-packing functional.
 struct CPEuclideanMaps {
     CPFMapI f_idx;     ///< DOF index per face (−1 = pinned)
     CPEMapD theta_e;   ///< intersection angle per edge (default π/2 = orthogonal)
@@ -184,11 +189,8 @@ inline double dof_val(int idx, const std::vector<double>& x) noexcept
 
 } // namespace cp_detail
 
-// ── Energy ────────────────────────────────────────────────────────────────────
-//
-// Mirrors evaluateEnergyAndGradient in the Java code (lines 170-240) for the
-// energy accumulation only.  The gradient is computed in a dedicated function
-// below for clarity.
+/// CP-Euclidean energy value at DOF vector `x` (ρ per face).
+/// Mirrors `evaluateEnergyAndGradient()` in the Java original (lines 170-240).
 inline double cp_euclidean_energy(const ConformalMesh&        mesh,
                                     const std::vector<double>&  x,
                                     const CPEuclideanMaps&      m)
@@ -233,10 +235,8 @@ inline double cp_euclidean_energy(const ConformalMesh&        mesh,
     return E;
 }
 
-// ── Gradient ──────────────────────────────────────────────────────────────────
-//
-// ∂E/∂ρ_f = φ_f − Σ_{h: face(h)=f, !is_border(h)}  (p + θ*)
-//         OR (boundary):                            2 θ*
+/// CP-Euclidean gradient `∂E/∂ρ_f` (per face DOF).  Interior term
+/// `−(p + θ*)`, boundary term `−2 θ*`; see `setup_cp_euclidean_maps`.
 inline std::vector<double> cp_euclidean_gradient(const ConformalMesh&        mesh,
                                                    const std::vector<double>&  x,
                                                    const CPEuclideanMaps&      m)
@@ -280,12 +280,10 @@ inline std::vector<double> cp_euclidean_gradient(const ConformalMesh&        mes
     return G;
 }
 
-// ── Hessian (analytic) ────────────────────────────────────────────────────────
-//
-// Per interior undirected edge e with adjacent faces (j, k):
-//   h_jk = sin θ / (cosh(Δρ) − cos θ)
-// Diagonal contributions on both endpoints; off-diagonal block is −h_jk.
-// Pinned faces are skipped (their DOF index is −1 ⇒ excluded from the matrix).
+/// Analytic CP-Euclidean Hessian, sparse.  Per interior edge `(j,k)`
+/// the contribution is `h_jk = sin θ / (cosh(Δρ) − cos θ)`, added to
+/// diagonals `H_jj`, `H_kk` and subtracted off-diagonals `H_jk = H_kj`.
+/// Pinned faces are excluded (DOF index −1).
 inline Eigen::SparseMatrix<double> cp_euclidean_hessian(const ConformalMesh&        mesh,
                                                           const std::vector<double>&  x,
                                                           const CPEuclideanMaps&      m)
@@ -323,11 +321,8 @@ inline Eigen::SparseMatrix<double> cp_euclidean_hessian(const ConformalMesh&
     return H;
 }
 
-// ── Finite-difference gradient check ─────────────────────────────────────────
-//
-// Mirrors the Java FunctionalTest pattern:
-//   For each DOF i, compare analytic G[i] to (E(x+ε·e_i) − E(x−ε·e_i)) / (2ε).
-// Default tolerance 1e-6 with ε = 1e-5 leaves ~3 digits of margin for sane meshes.
+/// FD gradient check for the CP-Euclidean functional.  Mirrors the
+/// Java `FunctionalTest`; default `eps = 1e-5`, `tol = 1e-6`.
 inline bool gradient_check_cp_euclidean(const ConformalMesh&        mesh,
                                           const std::vector<double>&  x,
                                           const CPEuclideanMaps&      m,
@@ -355,10 +350,8 @@ inline bool gradient_check_cp_euclidean(const ConformalMesh&        mesh,
     return true;
 }
 
-// ── Finite-difference Hessian check ──────────────────────────────────────────
-//
-// Verifies analytic H against ( G(x+ε·e_i) − G(x−ε·e_i) ) / (2ε) column-wise.
-// Symmetry is implicit in the analytic form; we check both off-diagonal entries.
+/// FD Hessian check for the CP-Euclidean functional.  Verifies analytic
+/// `H` column-by-column against `(G(x+εe_j) − G(x−εe_j)) / (2ε)`.
 inline bool hessian_check_cp_euclidean(const ConformalMesh&        mesh,
                                          const std::vector<double>&  x,
                                          const CPEuclideanMaps&      m,