docs(api): prefer builder-based fallible examples (#214)

[acgetchell]

• Present DelaunayTriangulationBuilder as the primary construction path while retaining DelaunayTriangulation::new as a legacy convenience constructor.
• Replace doctest unwrap() patterns with typed ? propagation and explicit optional guards across construction, validation, repair, geometry, and topology examples.
• Re-export DelaunayTriangulationBuilder from prelude::delaunayize so single-prelude delaunayize examples can use the builder directly.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 908d5594-b343-4217-acab-d775eb5cbffe

📥 Commits

Reviewing files that changed from the base of the PR and between 2b396d6 and 207ab3e.

📒 Files selected for processing (1)

• src/geometry/algorithms/convex_hull.rs

---

Walkthrough

This PR migrates Rust doc examples and doctests across the repository to use DelaunayTriangulationBuilder for construction and Result/?-based example scaffolding, and adds a prelude re-export for the builder.

Changes

Builder API Documentation and Examples Refactoring

Layer / File(s)	Summary
Prelude and public re-exports src/lib.rs, tests/prelude_exports.rs	Adds DelaunayTriangulationBuilder re-export in the delaunayize prelude and updates the related test/doctest imports and construction call.
Top-level documentation guides README.md, docs/api_design.md, docs/diagnostics.md, docs/numerical_robustness_guide.md, docs/validation.md, docs/workflows.md	High-level docs and examples rewritten to demonstrate builder-based construction (build::<()>()?) and result-based error handling (?) instead of unwrap()/convenience constructors.
Adjacency & boundary examples src/core/adjacency.rs, src/core/boundary.rs, src/core/traits/boundary_analysis.rs, src/core/traits/facet_cache.rs	Rustdoc examples updated to use the builder API, iterator-safe access (let Some(...) else { return Ok(()); }), and Result-returning doctest harnesses.
Construction, builder, and validation examples src/delaunay/builder.rs, src/delaunay/construction.rs, src/delaunay/delaunayize.rs, src/delaunay/validation.rs, src/core/repair.rs, src/core/validation.rs	Core API doctests converted to builder construction, typed ExampleError scaffolding where needed, and ?-propagation in examples.
Query and mutation examples src/core/query.rs, src/core/edge.rs, src/core/facet.rs, src/core/simplex.rs, src/core/collections/...	Many accessor and mutation doc examples rewritten to use builder construction and fallible control flow, avoiding unwrap() in doctests.
Algorithm and utility examples src/core/algorithms/*, src/delaunay/*, src/core/util/*	Algorithmic examples (insert, locate, flips, repair, Jaccard, facet-keys, etc.) updated to builder-based construction and Result/?-based example scaffolding.
TDS core examples (large) src/core/tds.rs	Extensive migration of TDS-related examples (simplices, vertices, keys, insertion/removal, neighbors, validation) to builder construction and Result-based doctests.
Geometry & topology examples src/geometry/*, src/topology/*, src/core/vertex.rs	Geometry and topology doc examples updated to use builder construction and Result-returning example main functions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Replace public doctest unwraps with typed Result examples #365 — Migrates public doctest examples from unwrap/expect to typed Result/?-based scaffolding and builder usage.
• Migrate all doctests to use DelaunayTriangulationBuilder API #214 — Broad refactor aligning docs and doctests to DelaunayTriangulationBuilder::new(...).build::<()>()? patterns.

Possibly related PRs

• acgetchell/delaunay#90: Related boundary-facet / FacetView iterator refactor that aligns with updated boundary examples.
• acgetchell/delaunay#303: Related prelude and re-export changes; this PR adds the builder re-export to the delaunayize prelude.
• acgetchell/delaunay#139: Overlaps on validation guide examples (Level 3 manifold validation) updated here to builder/? patterns.

🐰 The builder hops into view tonight,
Examples trade unwrap for polite "?" flight.
Error enums tucked in rows so neat,
Doctests now compile and greet.
Hooray — the docs and tests feel light!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: documentation updates to prefer builder-based examples with fallible error handling instead of unwrap() patterns.
Description check	✅ Passed	The description is directly related to the changeset, clearly explaining the three main objectives: promoting the builder API, replacing unwrap() with typed error propagation, and re-exporting DelaunayTriangulationBuilder.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 100.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/214-builder-doctest-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity

Metric	Results
Complexity	0

View in Codacy

🟢 Coverage ∅ diff coverage · +0.01% coverage variation

Metric	Results
Coverage variation	✅ +0.01% coverage variation (-1.00%)
Diff coverage	✅ ∅ diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (1789ceb)	62454	56531	90.52%
Head commit (207ab3e)	62454 (+0)	56536 (+5)	90.52% (+0.01%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#409)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/geometry/algorithms/convex_hull.rs`:
- Around line 2005-2006: Update the doc comment to match the implementation:
instead of claiming the helper uses DelaunayTriangulationBuilder and returns a
reference to Triangulation, state that create_triangulation constructs and
returns a DelaunayTriangulation (built via
DelaunayTriangulation::with_kernel(...)). Mention the actual ownership return
type and the use of with_kernel rather than the builder so the comment aligns
with the create_triangulation implementation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: aef5905d-9e99-42f2-844f-191bfbc3168e

📥 Commits

Reviewing files that changed from the base of the PR and between 1789ceb and 2b396d6.

📒 Files selected for processing (45)

• README.md
• docs/api_design.md
• docs/diagnostics.md
• docs/numerical_robustness_guide.md
• docs/validation.md
• docs/workflows.md
• src/core/adjacency.rs
• src/core/algorithms/flips.rs
• src/core/algorithms/incremental_insertion.rs
• src/core/algorithms/locate.rs
• src/core/boundary.rs
• src/core/collections/key_maps.rs
• src/core/collections/secondary_maps.rs
• src/core/edge.rs
• src/core/facet.rs
• src/core/query.rs
• src/core/repair.rs
• src/core/simplex.rs
• src/core/tds.rs
• src/core/traits/boundary_analysis.rs
• src/core/traits/facet_cache.rs
• src/core/util/delaunay_validation.rs
• src/core/util/facet_keys.rs
• src/core/util/jaccard.rs
• src/core/validation.rs
• src/core/vertex.rs
• src/delaunay/builder.rs
• src/delaunay/construction.rs
• src/delaunay/delaunayize.rs
• src/delaunay/flips.rs
• src/delaunay/insertion.rs
• src/delaunay/query.rs
• src/delaunay/repair.rs
• src/delaunay/serialization.rs
• src/delaunay/triangulation.rs
• src/delaunay/validation.rs
• src/geometry/algorithms/convex_hull.rs
• src/geometry/quality.rs
• src/geometry/util/measures.rs
• src/geometry/util/triangulation_generation.rs
• src/lib.rs
• src/topology/characteristics/euler.rs
• src/topology/characteristics/validation.rs
• src/topology/manifold.rs
• tests/prelude_exports.rs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.51%. Comparing base (1789ceb) to head (207ab3e).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #409   +/-   ##
=======================================
  Coverage   90.50%   90.51%           
=======================================
  Files          71       71           
  Lines       62244    62244           
=======================================
+ Hits        56335    56340    +5     
+ Misses       5909     5904    -5     

Flag	Coverage Δ
unittests	90.51% <ø> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.