Slipstream/eventcore

Fork 0

docs: documentation completeness audit (#244) #416

Merged

jwilger merged 1 commit from docs/244-documentation-audit into main

2026-06-13 10:51:06 -07:00

jwilger commented

2026-06-13 09:37:08 -07:00

Owner

Summary

Documentation completeness audit (#244), focused on reconciling the manual + rustdoc against the current API and fixing inaccuracies.

Stale-API reconciliation

Streaming reads (#364 / ADR-0049): docs/manual/03-core-concepts/02-events-and-stores.md showed read_stream returning the removed EventStreamReader<E>. Rewritten to the current lazy EventStream<E> + collect_events helper, with a migration note linking ADR-0049. (The only non-ADR doc referencing the removed type.)
Glob filtering (#246 / ADR-0047): projections getting-started page now documents EventFilter::all/prefix/pattern (literal StreamPrefix vs glob StreamPattern).

Error-type accuracy

08-reference/03-error-reference.md was fictional (invented variants + fake CE001–CE008 codes). Rewritten to the real CommandError (BusinessRuleViolation, ConcurrencyError, EventStoreError, ValidationError) and EventStoreError (VersionConflict, UndeclaredStream, Deserialization/SerializationFailed, StoreFailure, ConflictingExpectedVersions) with per-variant cause/resolution.
Fixed fabricated CommandError matches and RetryPolicy/BackoffStrategy usage in error-handling, troubleshooting, web-API, and configuration-reference pages.

Getting Started

eventcore/src/lib.rs had no crate-level rustdoc. Added a //! overview + a runnable quickstart doctest (in-memory store, events → #[derive(Command)] → CommandLogic → execute()) that a newcomer can follow quickly.

Terminology + cross-references

ExecutionResult → ExecutionResponse (the real type) across the manual; fixed the README quickstart Cargo.toml (correct version, eventcore-memory as a separate crate, removed nonexistent feature).

Verification

cargo clippy --workspace --all-targets --all-features -- -D warnings clean
cargo test --doc --workspace — 9 passed, 0 failed (new quickstart runs)
cargo nextest run --workspace — 277 passed

ADRs intentionally left untouched (historical records per .claude/rules/adrs.md).

Closes #244

## Summary Documentation completeness audit (#244), focused on reconciling the manual + rustdoc against the current API and fixing inaccuracies. ## Stale-API reconciliation - **Streaming reads (#364 / ADR-0049):** `docs/manual/03-core-concepts/02-events-and-stores.md` showed `read_stream` returning the removed `EventStreamReader<E>`. Rewritten to the current lazy `EventStream<E>` + `collect_events` helper, with a migration note linking ADR-0049. (The only non-ADR doc referencing the removed type.) - **Glob filtering (#246 / ADR-0047):** projections getting-started page now documents `EventFilter::all/prefix/pattern` (literal `StreamPrefix` vs glob `StreamPattern`). ## Error-type accuracy - `08-reference/03-error-reference.md` was fictional (invented variants + fake `CE001`–`CE008` codes). Rewritten to the real `CommandError` (`BusinessRuleViolation`, `ConcurrencyError`, `EventStoreError`, `ValidationError`) and `EventStoreError` (`VersionConflict`, `UndeclaredStream`, `Deserialization/SerializationFailed`, `StoreFailure`, `ConflictingExpectedVersions`) with per-variant cause/resolution. - Fixed fabricated `CommandError` matches and `RetryPolicy`/`BackoffStrategy` usage in error-handling, troubleshooting, web-API, and configuration-reference pages. ## Getting Started - `eventcore/src/lib.rs` had **no crate-level rustdoc**. Added a `//!` overview + a **runnable quickstart doctest** (in-memory store, events → `#[derive(Command)]` → `CommandLogic` → `execute()`) that a newcomer can follow quickly. ## Terminology + cross-references - `ExecutionResult` → `ExecutionResponse` (the real type) across the manual; fixed the README quickstart `Cargo.toml` (correct version, `eventcore-memory` as a separate crate, removed nonexistent feature). ## Verification - `cargo clippy --workspace --all-targets --all-features -- -D warnings` clean - `cargo test --doc --workspace` — 9 passed, 0 failed (new quickstart runs) - `cargo nextest run --workspace` — 277 passed ADRs intentionally left untouched (historical records per `.claude/rules/adrs.md`). Closes #244

jwilger added 1 commit

2026-06-13 09:37:08 -07:00

docs: documentation completeness audit (#244 )

CI / Clippy (pull_request) Successful in 3m18s

Details

CI / Security Audit (pull_request) Successful in 38s

Details

CI / Mutation (pull_request) Has been skipped

Details

CI / Detect Changes (pull_request) Successful in 5s

Details

CI / Request auto_review semantic review (pull_request) Successful in 2s

Details

CI / Format (pull_request) Successful in 23s

Details

CI / Test (pull_request) Successful in 5m3s

Details

CI / CI Gate (pull_request) Successful in 2s

Details

auto_review auto_review: no findings

b090786f75

Reconcile documentation against recent API changes and improve coverage of
the primary public surface so the library is release-ready.

Stale-API reconciliation (streaming reads, #364 / ADR-0049):
- Update the EventStore trait illustration in the core-concepts manual to show
  read_stream returning a lazy EventStream<E> instead of the removed
  EventStreamReader, and document collect_events as the "collect into Vec"
  helper. Add a migration note pointing at ADR-0049.

Error-type accuracy (troubleshooting / error reference):
- Rewrite docs/manual/08-reference/03-error-reference.md to match the real
  CommandError (BusinessRuleViolation, ConcurrencyError, EventStoreError,
  ValidationError) and EventStoreError variants, replacing the previously
  fabricated enum, invented error codes, and nonexistent ExecutionPhaseError.
- Fix the core-concepts error-handling page's CommandError definition and a
  stale match arm to the real variants.
- Fix the troubleshooting and web-API pages that matched on the nonexistent
  CommandError::ConcurrencyConflict / StreamNotFound / ValidationFailed and
  used RetryPolicy::none(); use ConcurrencyError and RetryPolicy::new() with
  max_retries(0) instead.
- Replace the fabricated RetryPolicy enum / RetryConfig struct in the
  configuration reference with the real builder-style RetryPolicy + the
  Fixed/Exponential BackoffStrategy variants.

Getting Started / first command:
- Add a crate-level //! doc to eventcore with a fully runnable quickstart
  doctest (in-memory store) walking through events, #[derive(Command)],
  CommandLogic, and execute(). Verified under cargo test --doc.

Glob pattern filtering (#246 / ADR-0047):
- Document EventFilter::all/prefix/pattern (StreamPrefix vs StreamPattern glob)
  in the projections getting-started page.

Terminology + cross-references:
- Rename ExecutionResult -> ExecutionResponse across the manual (the real type).
- Fix the README quick-start dependency snippet (correct version, separate
  eventcore-memory crate, no nonexistent "memory" feature).
- Cross-link the error reference from the error-handling page and link
  schema-evolution/versioning pages from deserialization guidance.

ADRs were left untouched as historical records per .claude/rules/adrs.md.
Manual markdown is not compiled by rustdoc (no include_str!), so only the
crate-level rustdoc example is doctest-gated; it compiles and runs.

Closes #244

auto-review approved these changes

2026-06-13 09:39:08 -07:00

auto-review left a comment

LLM usage and cost

Reasoning (gpt-4o) in=38470 out=16437 cost=$0.438905
Cheap (gpt-4o-mini) in=774 out=43 cost=$0.000142
Estimated total USD: $0.439047 via https://api.openai.com and https://api.openai.com

The documentation audit has successfully updated the manual and rustdoc to reflect the current API, addressing inaccuracies and improving clarity. The changes appear safe to merge, with no issues found in the diff. ## LLM usage and cost - Reasoning (gpt-4o) in=38470 out=16437 cost=$0.438905 - Cheap (gpt-4o-mini) in=774 out=43 cost=$0.000142 Estimated total USD: $0.439047 via https://api.openai.com and https://api.openai.com

jwilger merged commit 5bc09d4a3a into main

2026-06-13 10:51:06 -07:00

jwilger deleted branch docs/244-documentation-audit

2026-06-13 10:51:07 -07:00

jwilger referenced this pull request from a commit

2026-06-13 10:51:08 -07:00

docs: documentation completeness audit (#244) (#416)