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

@@ -48,13 +48,18 @@ namespace conformallab {
 
 // ── Property-map type aliases ─────────────────────────────────────────────────
 
+/// Property map vertex → `double` for the Euclidean functional.
 using EuclVMapD = ConformalMesh::Property_map<Vertex_index, double>;
+/// Property map vertex → `int`    for the Euclidean functional.
 using EuclVMapI = ConformalMesh::Property_map<Vertex_index, int>;
+/// Property map edge   → `double` for the Euclidean functional.
 using EuclEMapD = ConformalMesh::Property_map<Edge_index,   double>;
+/// Property map edge   → `int`    for the Euclidean functional.
 using EuclEMapI = ConformalMesh::Property_map<Edge_index,   int>;
 
 // ── Persistent map bundle ─────────────────────────────────────────────────────
 
+/// Bundle of the five property maps consumed by the Euclidean functional.
 struct EuclideanMaps {
     EuclVMapI v_idx;    ///< DOF index per vertex   (-1 = pinned / u_v = 0)
     EuclEMapI e_idx;    ///< DOF index per edge      (-1 = no edge DOF)
@@ -119,10 +124,9 @@ inline int euclidean_dimension(const ConformalMesh& mesh, const EuclideanMaps& m
     return dim;
 }
 
-// Set lambda0 from mesh vertex positions (Euclidean):
-//   λ°_e = 2·log(|p_i − p_j|)   (natural log of Euclidean edge length squared)
-//
-// This gives exp(Λ̃_ij / 2) = l_ij at x=0.
+/// Set `lambda0` from mesh vertex positions:
+/// `λ°_e = 2·log(|p_i − p_j|)` (natural log of Euclidean edge length²).
+/// This gives `exp(Λ̃_ij / 2) = l_ij` at `x = 0`.
 inline void compute_euclidean_lambda0_from_mesh(ConformalMesh& mesh, EuclideanMaps& m)
 {
     for (auto e : mesh.edges()) {
@@ -142,25 +146,23 @@ inline void compute_euclidean_lambda0_from_mesh(ConformalMesh& mesh, EuclideanMa
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
+/// Read DOF value from `x` for index `idx`; return 0 if pinned (idx < 0).
 static inline double eucl_dof_val(int idx, const std::vector<double>& x)
 {
     return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
 }
 
+/// Convert a CGAL half-edge index to a plain `std::size_t` for vector indexing.
 static inline std::size_t eucl_hidx(Halfedge_index h)
 {
     return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
 }
 
-// ── Gradient ──────────────────────────────────────────────────────────────────
-//
-// G_v = Θ_v − Σ_{faces adj. v} α_v(face)
-// G_e = α_opp(face⁺) + α_opp(face⁻) − φ_e
-//
-// Corner-angle storage (h_alpha):
-//   h_alpha[h] = corner angle OPPOSITE to the edge of halfedge h in its face.
-//   h_alpha[h0] = α3,  h_alpha[h1] = α1,  h_alpha[h2] = α2
-// (same convention as SphericalFunctional)
+/// Compute the Euclidean-functional gradient G(x):
+///   * `G_v = Θ_v − Σ_faces α_v(face)`
+///   * `G_e = α_opp(face⁺) + α_opp(face⁻) − φ_e`
+///
+/// Same half-edge corner-angle storage convention as `spherical_gradient`.
 inline std::vector<double> euclidean_gradient(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -238,9 +240,8 @@ inline std::vector<double> euclidean_gradient(
     return G;
 }
 
-// ── Energy via Gauss-Legendre path integral ───────────────────────────────────
-//
-// E(x) = ∫₀¹ ⟨G(tx), x⟩ dt   (10-point GL quadrature, same as SphericalFunctional)
+/// Euclidean energy `E(x) = ∫₀¹ ⟨G(t·x), x⟩ dt`, evaluated with
+/// 10-point Gauss-Legendre quadrature (same as the Spherical functional).
 inline double euclidean_energy(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -282,11 +283,14 @@ inline double euclidean_energy(
 
 // ── Full evaluation (energy + gradient) ──────────────────────────────────────
 
+/// Output of `evaluate_euclidean()` — energy plus optional gradient.
 struct EuclideanResult {
-    double              energy   = 0.0;
-    std::vector<double> gradient;
+    double              energy   = 0.0; ///< Functional value at input DOFs.
+    std::vector<double> gradient;       ///< Gradient ∇E (empty if not requested).
 };
 
+/// Evaluate the Euclidean functional at DOFs `x`.  Returns energy and
+/// gradient (toggle via `need_energy` / `need_gradient`).
 inline EuclideanResult evaluate_euclidean(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -302,10 +306,8 @@ inline EuclideanResult evaluate_euclidean(
     return res;
 }
 
-// ── Finite-difference gradient check ─────────────────────────────────────────
-//
-// Tests |G[i] − (E(x+εeᵢ) − E(x−εeᵢ))/(2ε)| / max(1,|G[i]|) < tol
-// for all variable DOFs.
+/// Finite-difference gradient check for the Euclidean functional
+/// (central differences).  Defaults `eps = 1e-5`, `tol = 1e-4`.
 inline bool gradient_check_euclidean(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,