docs: drive Doxygen coverage to 100 percent + auto-generate headers.md #17
Reference in New Issue
Block a user
No description provided.
Delete Branch "docs/doxygen-coverage-100"
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?
Three commits.
Live HTML: https://tmoussa.codeberg.page/ConformalLabpp/
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>Replaces the hand-maintained `doc/api/headers.md` with a generated one sourced from each header's `\file` brief and the public symbols extracted by Doxygen into XML. The CI workflow regenerates it on every push to main that touches the public headers. New files ───────── * scripts/gen-headers-md.py — parses doc/doxygen/xml/*.xml, groups headers by directory (CGAL public / CGAL internals / Core), and writes a markdown table with header path, first-sentence brief, and the public symbols declared at file scope. Skips `detail::` namespaces and template-specialisation duplicates. * scripts/regen-docs.sh — convenience wrapper: doxygen → gen-headers-md.py → coverage report. Workflow changes ──────────────── .gitea/workflows/doxygen-pages.yml now: 1. Runs `bash scripts/doxygen-coverage.sh` as an informational step (no fail threshold yet — the script supports `--threshold N` for when we're ready). 2. Re-runs `python3 scripts/gen-headers-md.py` and warns if the file drifted from what's in main (operator should run `regen-docs.sh` locally before pushing). Doxyfile hygiene ──────────────── `HTML_TIMESTAMP` was removed in Doxygen 1.10 → replaced with the new `TIMESTAMP = NO` to silence the obsolete-tag warning. Effect on the reviewer-facing landing pages ─────────────────────────────────────────── Every improvement to a `\file` brief at the top of a public header now flows automatically into both: * the Doxygen HTML at https://tmoussa.codeberg.page/ConformalLabpp/ * the markdown landing at doc/api/headers.md (rendered by Codeberg in the repo view) …so writers have a single source of truth (the C++ source) and readers see the same words in both surfaces. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>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>docs: drive Doxygen toward near-100 percent + auto-generate headers.mdto docs: drive Doxygen coverage to 100 percent + auto-generate headers.md