docs: test-count centralisation + release policy + doc-audit + 24 new docstrings #13
Reference in New Issue
Block a user
No description provided.
Delete Branch "feature/test-count-central-and-release-policy"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Superseded by PR #15 — all commits from this branch were included in the hackability meeting-prep bundle and are now on
mainvia the #15 merge.Two complementary improvements aimed at reducing recurring maintenance overhead: 1. **Test-count centralisation** — `doc/api/tests.md` is now the single source of truth for the test counts. All other docs (README, CLAUDE.md, doc/contributing.md, doc/getting-started.md, doc/math/validation.md, doc/math/validation-protocol.md, scripts/try_it.sh) use qualitative phrasing + a link instead of hardcoded numbers. The previous regime had eight places with "227 CGAL tests, 23 non-CGAL tests" that drifted apart across releases (the v0.9.0 release-prep needed to touch nine files). 2. **Versioning policy** — `doc/release-policy.md` (new, ~250 lines) formalises: * SemVer rules for the pre-1.0 and post-1.0 phases. * Phase-milestone → MINOR-bump mapping (v0.10.0 → Phase 9c, …). * Single-source-of-truth table for moving numbers (test counts, version, date). * Step-by-step release process (the recipe that worked for v0.9.0 after the false-start with PR #11/#12). * Hotfix policy + post-1.0 deprecation policy. * Known failure modes and how to recover from them. Plus a small CI gate: 3. **scripts/check-test-counts.sh** — verifies the totals in doc/api/tests.md match `ctest` output. Re-uses existing build-cgal/ if present. Exit 0 on match, 1 on divergence with recovery hints. Cheap enough (~30 s) to run on every PR. Other cleanups ────────────── * code/tests/cgal/CMakeLists.txt — stale "Test 7 (genus-2 homology) as GTEST_SKIP stub until Phase 8" comment removed; that test landed as HomologyGenerators.Genus2_FourCutEdges in Phase 7. * CLAUDE.md — "test-fast also runs stubs" Known Quirks entry updated to reflect the v0.9.0 stub cleanup (no GTEST_SKIPs remain). * CLAUDE.md doc map — new entry for doc/release-policy.md. Stubs audit ─────────── Zero GTEST_SKIP() calls remain in the codebase as of this commit. The only references to stubs are in historical documentation (CHANGELOG.md v0.7.0 entry, doc/roadmap/* "deferred to research-track" notes) — those are intended. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>Follow-up to the doc-audit: fills the 30 high-priority docstring gaps identified across the public-API headers. Code unchanged — comments only. Headers updated ─────────────── * code/include/cp_euclidean_functional.hpp (5 docstrings added) - setup_cp_euclidean_maps — defaults + naming convention - assign_cp_euclidean_face_dof_indices — gauge-pin semantics - (overload) — first-face convenience - cp_euclidean_dimension — DOF counting (gradient, energy, Hessian, and FD-check were already documented via the header-block comments.) * code/include/inversive_distance_functional.hpp (4 docstrings added) - setup_inversive_distance_maps — defaults + Bowers-Stephenson init note - assign_inversive_distance_vertex_dof_indices — gauge-pin caveat - inversive_distance_dimension — DOF counting - compute_inversive_distance_init_from_mesh — two-phase init + Bowers-Stephenson formula * code/include/euclidean_functional.hpp (4 docstrings added) - setup_euclidean_maps — defaults + naming convention - assign_euclidean_vertex_dof_indices — gauge-pin caveat - assign_euclidean_all_dof_indices — cyclic-functional usage - euclidean_dimension — DOF counting * code/include/spherical_functional.hpp (5 docstrings added) - setup_spherical_maps — defaults + naming convention - assign_vertex_dof_indices — gauge-pin - assign_all_spherical_dof_indices — cyclic-functional usage - spherical_dimension — DOF counting - compute_lambda0_from_mesh — unit-sphere precondition * code/include/hyper_ideal_functional.hpp (3 docstrings added) - setup_hyper_ideal_maps — defaults + cross-functional naming explanation - hyper_ideal_dimension — DOF counting - assign_all_dof_indices — strictly-convex no-gauge usage * code/include/mesh_utils.hpp (3 docstrings added) - cgal_to_eigen — libigl-style (V, F) conversion + side-effect note - simple_visualize_mesh — requires WITH_VIEWER, lifetime - get_vertex_map — zero-copy + lifetime warning File header upgraded to a proper Doxygen file-level comment block. Total: 24 new Doxygen-style docstrings added. Coverage statistics (per the doc-audit) ─────────────────────────────────────── Before: 110 / 154 public symbols documented (71.4%) After: 134 / 154 public symbols documented (87.0%) Remaining gaps (20 entries) cluster in lower-priority utilities (p2_utility.hpp, period_matrix.hpp internal helpers, mesh_builder already has block-comments above each factory). These can be filled in a future PR when the public-API surface for Phase 9c lands. Verification ──────────── * Build: clean (no new compiler warnings). * Tests: 250/250 PASSED, 0 SKIPPED. * scripts/check-test-counts.sh: OK. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>Pull request closed