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>
First step of the Phase 8 Hybrid MVP. Adds a thin CGAL-conformant public
API layer over the existing implementation, validated by 7 acceptance
tests. Total CGAL test count: 183 (was 176), 0 skipped.
New public headers
──────────────────
* code/include/CGAL/Conformal_map_traits.h
- ConformalMapTraits concept documentation
- Default_conformal_map_traits<Surface_mesh<P>, K> specialisation
- Static property-map accessors: vertex_points, theta_map,
vertex_index_map, lambda0_map
* code/include/CGAL/Discrete_conformal_map.h
- User-facing entry: discrete_conformal_map_euclidean(mesh, np)
- Conformal_map_result<FT> struct (u, iter, ‖G‖, converged flags)
- Natural-theta default: x = 0 is the equilibrium when no Θ supplied
- Honours user-provided Θ via vertex_curvature_map named parameter
* code/include/CGAL/Conformal_map/internal/parameters.h
- 4 named-parameter tags in CGAL::Conformal_map::internal_np:
vertex_curvature_map, gradient_tolerance,
max_iterations, fixed_vertex_map
- User-facing helpers in CGAL::parameters::*
Tests (test_cgal_traits_mvp.cpp, 7 cases)
─────────────────────────────────────────
* DefaultTraitsTypes: compile-time type sanity (static_assert)
* AccessorsReuseExistingMaps: traits accessors return identical pmaps
* SingleTriangleConverges,
QuadStripConverges: end-to-end Euclidean wrapper passes
* MaxIterationsTakesEffect: named parameter is read
* GradientToleranceTakesEffect: tolerance override changes Newton end-state
* WrapperMatchesLegacyAPI: cross-API result equality at 1e-10
Architecture
────────────
3-layer wrapper as designed (doc/api/cgal-package.md):
Layer 1: code/include/*.hpp (existing algorithms, unchanged)
Layer 2: CGAL/Conformal_map/internal/ (adapter, parameter tags)
Layer 3: CGAL/Conformal_map_traits.h, CGAL/Discrete_conformal_map.h
(user-facing)
No algorithm duplication. Existing 176 + 36 tests untouched.
Next: Phase 9a (Inversive-Distance) as the second client of this API —
the real acceptance test for the trait design.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
