conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Tarik Moussa
2026-05-23 23:44:54 +02:00
parent 8869ead3c9
commit e04515c423
13 changed files with 425 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
code/include/CGAL/Conformal_map_traits.h
View File

@@ -110,20 +110,33 @@ selected automatically when `TriangleMesh = CGAL::Surface_mesh<...>`.
template <typename K>
struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
{
/// The CGAL kernel parameter; defaults to `Simple_cartesian<double>`.
using Kernel = K;
/// Field type used for all scalar conformal-map data (lengths, λ, Θ, …).
using FT = typename K::FT;
/// 3-D point type used for vertex coordinates.
using Point_3 = typename K::Point_3;
/// The triangle-mesh type this specialisation targets.
using Triangle_mesh = CGAL::Surface_mesh<Point_3>;
/// Boost-graph vertex descriptor for `Triangle_mesh`.
using Vertex_descriptor = typename boost::graph_traits<Triangle_mesh>::vertex_descriptor;
/// Boost-graph half-edge descriptor for `Triangle_mesh`.
using Halfedge_descriptor = typename boost::graph_traits<Triangle_mesh>::halfedge_descriptor;
/// Boost-graph edge descriptor for `Triangle_mesh`.
using Edge_descriptor = typename boost::graph_traits<Triangle_mesh>::edge_descriptor;
/// Boost-graph face descriptor for `Triangle_mesh`.
using Face_descriptor = typename boost::graph_traits<Triangle_mesh>::face_descriptor;
// Property-map types — match the names used by setup_euclidean_maps().
/// Property map vertex → `Point_3` (the mesh's geometric embedding).
using Vertex_point_map = typename Triangle_mesh::template Property_map<Vertex_descriptor, Point_3>;
/// Property map vertex → target cone angle Θᵥ in radians (legacy name `ev:theta`).
using Theta_pmap = typename Triangle_mesh::template Property_map<Vertex_descriptor, FT>;
/// Property map vertex → contiguous integer index (legacy name `ev:idx`).
using Vertex_index_pmap = typename Triangle_mesh::template Property_map<Vertex_descriptor, int>;
/// Property map edge → log of original edge length λ⁰ (legacy name `ee:lam0`).
using Lambda0_pmap = typename Triangle_mesh::template Property_map<Edge_descriptor, FT>;
// ─── Property-map accessors ───────────────────────────────────────────
@@ -133,10 +146,12 @@ struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
// calling either `setup_euclidean_maps(m)` first or the accessor first
// is equivalent.
/// Return the built-in vertex-point map of `m` (the geometric embedding).
static Vertex_point_map vertex_points(Triangle_mesh& m) {
return m.points();
}
/// Return (or create with default 2π) the target-angle property map.
static Theta_pmap theta_map(Triangle_mesh& m) {
auto [pm, created] = m.template add_property_map<Vertex_descriptor, FT>(
"ev:theta", FT(2.0 * 3.141592653589793238));
@@ -144,6 +159,7 @@ struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
return pm;
}
/// Return (or create with default −1) the vertex-index property map.
static Vertex_index_pmap vertex_index_map(Triangle_mesh& m) {
auto [pm, created] = m.template add_property_map<Vertex_descriptor, int>(
"ev:idx", -1);
@@ -151,6 +167,7 @@ struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
return pm;
}
/// Return (or create with default 0) the λ⁰ (initial log-length) property map.
static Lambda0_pmap lambda0_map(Triangle_mesh& m) {
auto [pm, created] = m.template add_property_map<Edge_descriptor, FT>(
"ee:lam0", FT(0));