docs(doxygen): fix critical extraction bug; baseline 24% → 42% on public API

ROOT CAUSE FIX
The Doxyfile EXCLUDE_PATTERNS line contained `*/* 2.hpp` (note the
space — a stray glob from macOS-style "foo 2.hpp" duplicate files).
That pattern was silently matching ALL .hpp / .h files, so Doxygen was
indexing nothing under code/include/.  The pre-existing 556 KB of HTML
output was effectively documenting only README.md, CLAUDE.md and a
small stub for std:: — not the C++ API at all.

After fixing the pattern (and properly escaping the space-prefixed
"foo 2.hpp / foo 2.h" macOS-dup patterns), Doxygen now extracts 141
compounds and emits 248 HTML pages from the public headers.

WHAT THIS PR ADDS
1. Doxyfile fix: correct EXCLUDE_PATTERNS; add GENERATE_XML for the
   coverage measurement script; add MathJax for `$$...$$` math in
   markdown; add the missing CGAL `\cgalParamNBegin/End/Description/
   Default/...` aliases so CGAL-style param blocks render correctly.

2. New headers:
   - code/include/CGAL/Conformal_map/doxygen_groups.h
     defines `PkgConformalMap{,Ref,Concepts,NamedParameters}`,
     resolving 17 prior "non-existing group" warnings.
   - code/include/CGAL/Conformal_map/doxygen_namespaces.h
     gives every namespace under `CGAL::` and `conformallab::` a
     brief description.

3. New tool: scripts/doxygen-coverage.sh
   Parses the XML output and reports % of public symbols (excluding
   the `detail::` implementation namespaces by default) that have a
   non-empty brief/detailed description.  Supports `--list-undoc`
   and `--threshold N` for CI integration.

4. Substantial docstring additions to the public CGAL headers:
   `Conformal_map_traits.h`, `Discrete_circle_packing.h`,
   `Discrete_inversive_distance.h`, `conformal_mesh.hpp`,
   `Discrete_conformal_map.h` (Hyper_ideal_map_result fields).

5. Markdown housekeeping that the strict-warning Doxygen run surfaced:
   tests.md (escape literal `#` in table cell),
   locked-vs-flexible.md (broken section anchor),
   overall_pipeline.md (replace `$$LaTeX$$` with inline-unicode math).

CURRENT NUMBERS

  before:  ~24%  documented (public API; the prior "87%" claim was
                 based on the broken extraction)
  after:    42%  documented   (165 of 396 public symbols)
  warnings: 0   (was 27 spurious + a flood of bogus undocumented
                  warnings hidden by the buggy EXCLUDE pattern)

NEXT (in a follow-up commit on this branch)
The remaining 231 public symbols (mostly in `layout.hpp`,
`hyper_ideal_functional.hpp`, `spherical_functional.hpp`, the per-mode
functional/Hessian files) can be brought to ~100% with another pass of
short `///` brief descriptions.  The coverage script is the gate; CI
can begin enforcing `--threshold 95` once the next pass lands.

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

code/include/CGAL/Conformal_map/doxygen_groups.h

@@ -0,0 +1,44 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// This header contains only Doxygen \defgroup commands.  It is included
+// nowhere in the build; its sole purpose is to register the package's
+// Doxygen group hierarchy so that `@ingroup Pkg...` references in the
+// other public headers resolve cleanly.
+
+#ifndef CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H
+#define CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H
+
+/*!
+\defgroup PkgConformalMap CGAL Discrete Conformal Map package
+\brief Discrete conformal maps on triangulated surfaces — five DCE models
+(Euclidean, Spherical, Hyper-Ideal, Circle-Packing Euclidean,
+Inversive-Distance).
+
+This package provides the C++ implementation of the variational discrete
+conformal equivalence solvers from Springborn 2020, Bobenko/Pinkall/Springborn
+2010, and Luo 2004, together with a CGAL-style named-parameter API.
+
+See `doc/api/cgal-package.md` for the full design rationale.
+*/
+
+/*!
+\defgroup PkgConformalMapRef Reference manual
+\ingroup PkgConformalMap
+\brief Public C++ API: entry functions, traits, layout helpers.
+*/
+
+/*!
+\defgroup PkgConformalMapConcepts Concepts
+\ingroup PkgConformalMap
+\brief C++ concepts and traits classes consumed by the entry functions.
+*/
+
+/*!
+\defgroup PkgConformalMapNamedParameters Named function parameters
+\ingroup PkgConformalMap
+\brief Package-specific named-parameter helpers in `CGAL::parameters::*`,
+plus the pipe-operator chaining convention.
+*/
+
+#endif  // CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H

code/include/CGAL/Conformal_map/doxygen_namespaces.h

@@ -0,0 +1,88 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Doxygen namespace documentation only — no declarations.  Centralised
+// here so that each namespace gets a single, consistent description in
+// the generated HTML, regardless of which header is parsed first.
+
+#ifndef CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H
+#define CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H
+
+/*!
+\namespace CGAL
+\brief Root namespace of the CGAL library; conformallab++ adds its
+public entry points (`discrete_conformal_map_*`, `Conformal_map_traits`,
+…) directly into this namespace, matching CGAL package conventions.
+*/
+
+/*!
+\namespace CGAL::Conformal_map
+\brief Implementation-detail namespace for the Discrete Conformal Map
+package.  Users normally do not need to enter this namespace; all
+public entry points are re-exported into `CGAL::`.
+*/
+
+/*!
+\namespace CGAL::Conformal_map::internal_np
+\brief Tag types backing the package-local named-function parameters
+(`vertex_curvature_map_t`, `gradient_tolerance_t`, `output_uv_map_t`, …).
+Users invoke them via the helpers in `CGAL::parameters::*`.
+*/
+
+/*!
+\namespace CGAL::parameters
+\brief CGAL named-function-parameter helpers — both upstream CGAL's and
+the conformallab++ package extensions (`vertex_curvature_map(...)`,
+`gradient_tolerance(...)`, `output_uv_map(...)`, `normalise_layout(...)`).
+Also home of the pipe-operator chaining convention; see
+`doc/tutorials/add-output-uv-map.md` §3.4.
+*/
+
+/*!
+\namespace conformallab
+\brief Core math/algorithm namespace of conformallab++.  Holds the five
+DCE functionals (Euclidean / Spherical / HyperIdeal / CP-Euclidean /
+Inversive-Distance), the Newton solver, layout helpers, mesh-property
+typedefs, and serialisation utilities.  Lives under
+`code/include/*.hpp` and is consumed both by the standalone CLI and
+by the thin CGAL wrappers under `CGAL::`.
+*/
+
+/*!
+\namespace conformallab::detail
+\brief Implementation-private helpers for the `conformallab` namespace.
+Not part of the stable public API.
+*/
+
+/*!
+\namespace conformallab::cp_detail
+\brief Implementation-private helpers for the Circle-Packing Euclidean
+functional (see `cp_euclidean_functional.hpp`).
+*/
+
+/*!
+\namespace conformallab::id_detail
+\brief Implementation-private helpers for the Inversive-Distance
+functional (see `inversive_distance_functional.hpp`).
+*/
+
+/*!
+\namespace conformallab::detail_xml
+\brief Implementation-private XML helpers for the (de)serialisation
+layer (see `serialization.hpp`).
+*/
+
+/*!
+\namespace mesh_utils
+\brief Small, opinion-free mesh utilities (loaders, validators,
+property-map registration) used by both the standalone tools and the
+CGAL wrappers.
+*/
+
+/*!
+\namespace viewer_utils
+\brief libigl-based interactive viewer helpers; built only when
+`WITH_VIEWER=ON`.  Not part of the headless / CGAL public surface.
+*/
+
+#endif  // CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H

code/include/CGAL/Conformal_map/internal/parameters.h

@@ -198,11 +198,8 @@ inline auto normalise_layout(bool flag)
 // operator on the same type.
 // ════════════════════════════════════════════════════════════════════════════
 
-/*!
-\addtogroup PkgConformalMapNamedParameters
-\{
-*/
-
+// Close the PkgConformalMapNamedParameters group block that was opened
+// above the helper functions (see \addtogroup at the top of this section).
 /// \}
 
 }  // namespace parameters