docs(api): use typed errors in public examples (#365)

[acgetchell]

• Replace public doctest unwraps and expects with typed Result examples across core and geometry APIs.
• Use concrete crate errors or small local thiserror enums in guides instead of boxed dynamic errors.
• Clarify toroidal builder wording and point the README at the workflow docs for periodic construction.

Closes #365

[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: 956f4a50-a3fc-4c94-baa7-d96d04d89fed

📥 Commits

Reviewing files that changed from the base of the PR and between 238dc12 and c6755c8.

📒 Files selected for processing (22)

• README.md
• docs/api_design.md
• docs/archive/topology_integration_design_historical.md
• docs/dev/rust.md
• docs/diagnostics.md
• docs/validation.md
• docs/workflows.md
• src/core/algorithms/incremental_insertion.rs
• src/core/triangulation.rs
• src/core/util/deduplication.rs
• src/core/util/facet_utils.rs
• src/core/util/hilbert.rs
• src/core/util/jaccard.rs
• src/core/vertex.rs
• src/geometry/kernel.rs
• src/geometry/predicates.rs
• src/geometry/robust_predicates.rs
• src/geometry/util/circumsphere.rs
• src/geometry/util/conversions.rs
• src/geometry/util/measures.rs
• src/geometry/util/point_generation.rs
• src/geometry/util/triangulation_generation.rs

---

Walkthrough

This PR systematically replaces .unwrap() and Box<dyn Error> patterns in public documentation examples with typed, fallible main() -> Result<_, SpecificError> patterns and ? error propagation throughout the codebase.

Changes

Documentation doctest refactoring to typed Result patterns

Layer / File(s)	Summary
README and toroidal construction guidance README.md	Toroidal construction modes clarified: .toroidal() canonicalizes to fundamental domain, .toroidal_periodic() builds periodic quotient. Guidance added for boundary-facet and periodic neighbor use; DelaunayTriangulationBuilder reference changed from docs.rs URL to local source path.
API design and workflow documentation examples docs/api_design.md, docs/workflows.md, docs/diagnostics.md, docs/validation.md, docs/dev/rust.md, docs/archive/...	Multiple API and workflow examples converted to use locally-defined typed error enums (ExampleError, RepairExampleError, PeriodicExampleError, ValidationExampleError, DiagnosticsExampleError) with thiserror and #[from] conversions. Each example now uses fn main() -> Result<_, LocalError> and propagates construction/insertion/repair/invariant/flip errors via ?.
Core triangulation and utility function examples src/core/algorithms/incremental_insertion.rs, src/core/triangulation.rs, src/core/util/deduplication.rs, src/core/util/facet_utils.rs, src/core/util/hilbert.rs, src/core/util/jaccard.rs, src/core/vertex.rs	Rustdoc examples converted to fallible patterns with typed errors (InsertionError, FacetError, JaccardComputationError, etc.). Deduplication examples refactored to use vertex! macro for construction. All examples use main() -> Result and ? for error propagation.
Geometry kernel and predicate examples src/geometry/kernel.rs, src/geometry/predicates.rs, src/geometry/robust_predicates.rs	Examples for Kernel trait variants and geometric predicates (simplex_orientation, insphere_distance, insphere) converted to main() -> Result<(), CoordinateConversionError> or CircumcenterError with ?-based error propagation and # Ok(()) doctest scaffolding.
Geometry utility function examples src/geometry/util/circumsphere.rs, src/geometry/util/conversions.rs, src/geometry/util/measures.rs, src/geometry/util/point_generation.rs, src/geometry/util/triangulation_generation.rs	Comprehensive refactor across circumsphere, coordinate conversions, simplex measures, random point generation, and triangulation generation. All examples now use main() -> Result<_, SpecificError> importing error types (CircumcenterError, CoordinateConversionError, RandomPointGenerationError) alongside helper functions, with ?-based error propagation replacing .unwrap().

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• acgetchell/delaunay#365: The PR directly addresses this issue, converting all visible public doctest .unwrap() and Box<dyn Error> usage across src/ to typed Result<_, SpecificError> patterns with ? propagation as requested.

Possibly related PRs

• acgetchell/delaunay#409: Both PRs update the same rust doctest snippets across overlapping files (docs/diagnostics.md, docs/validation.md, docs/workflows.md) to use fallible main() -> Result patterns with typed errors instead of .unwrap() or dynamic error types.

Suggested labels

documentation, rust, api

Poem

🐰 The rabbits of code documentation rejoice—
No more unwraps that hide the voice!
Typed Result patterns now shine so clear,
Error handling shown without fear.
Examples that users can trust and compile,
Making the API review worthwhile! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: converting public API doctest examples to use typed errors instead of unwraps.
Description check	✅ Passed	The description accurately outlines the PR's objectives: replacing unwraps with typed Result examples, using concrete error types, and clarifying toroidal builder wording.
Linked Issues check	✅ Passed	The PR comprehensively addresses #365 requirements: replaces public doctest unwraps/expects with typed Result examples across core and geometry APIs, uses concrete crate errors and local thiserror enums instead of Box, and improves documentation clarity.
Out of Scope Changes check	✅ Passed	All changes are in-scope documentation and doctest updates focused on error handling in examples; no unrelated functionality or logic changes are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 100.00%.

_{✏️ 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/365-typed-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.00% coverage variation

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

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (238dc12)	62454	56536	90.52%
Head commit (c6755c8)	62454 (+0)	56536 (+0)	90.52% (+0.00%)

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 (#410)	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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.51%. Comparing base (238dc12) to head (c6755c8).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #410   +/-   ##
=======================================
  Coverage   90.51%   90.51%           
=======================================
  Files          71       71           
  Lines       62244    62244           
=======================================
  Hits        56340    56340           
  Misses       5904     5904           

Flag	Coverage Δ
unittests	90.51% <ø> (ø)

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.