docs: overhaul API documentation across all crates #420

Merged

jwilger merged 1 commit from docs/api-doc-comments-overhaul into main

2026-06-14 13:20:53 -07:00

jwilger commented

2026-06-14 13:17:04 -07:00

Owner

Summary

Add missing crate-level //! doc comments to eventcore-macros, eventcore-testing, eventcore-postgres, eventcore-sqlite, and eventcore-fs
Add /// doc comments to undocumented public types: error enums and store structs in postgres/sqlite backends
Fix pre-existing rustdoc errors in eventcore-types, eventcore-fs, and eventcore that caused cargo doc --workspace --no-deps to fail

Files changed

File	Change
`eventcore-macros/src/lib.rs`	Module overview for `#[derive(Command)]` macro
`eventcore-testing/src/lib.rs`	Module overview covering all five testing modules
`eventcore-postgres/src/lib.rs`	Module overview + docs on `PostgresEventStoreError` and `PostgresEventStore`
`eventcore-sqlite/src/lib.rs`	Module overview + docs on 3 error enums and `SqliteEventStore`
`eventcore-fs/src/lib.rs`	Fix private-module links that caused rustdoc errors
`eventcore-types/src/store.rs`	Fix unresolved-link errors from bare `[, ]` in glob metacharacter docs
`eventcore/src/lib.rs`	Fix private `ExecutePipeline` link and redundant explicit link targets

Test plan

cargo doc --workspace --no-deps completes with zero errors (was 13 errors before)
All 275 tests pass
cargo clippy --all-targets --all-features -- -D warnings clean

## Summary - Add missing crate-level `//!` doc comments to `eventcore-macros`, `eventcore-testing`, `eventcore-postgres`, `eventcore-sqlite`, and `eventcore-fs` - Add `///` doc comments to undocumented public types: error enums and store structs in postgres/sqlite backends - Fix pre-existing `rustdoc` errors in `eventcore-types`, `eventcore-fs`, and `eventcore` that caused `cargo doc --workspace --no-deps` to fail ## Files changed | File | Change | |------|--------| | `eventcore-macros/src/lib.rs` | Module overview for `#[derive(Command)]` macro | | `eventcore-testing/src/lib.rs` | Module overview covering all five testing modules | | `eventcore-postgres/src/lib.rs` | Module overview + docs on `PostgresEventStoreError` and `PostgresEventStore` | | `eventcore-sqlite/src/lib.rs` | Module overview + docs on 3 error enums and `SqliteEventStore` | | `eventcore-fs/src/lib.rs` | Fix private-module links that caused rustdoc errors | | `eventcore-types/src/store.rs` | Fix unresolved-link errors from bare `[, ]` in glob metacharacter docs | | `eventcore/src/lib.rs` | Fix private `ExecutePipeline` link and redundant explicit link targets | ## Test plan - [x] `cargo doc --workspace --no-deps` completes with zero errors (was 13 errors before) - [x] All 275 tests pass - [x] `cargo clippy --all-targets --all-features -- -D warnings` clean

jwilger added 1 commit

2026-06-14 13:17:04 -07:00

docs: overhaul API documentation across all crates

CI / Detect Changes (pull_request) Successful in 3s

Details

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

Details

auto_review auto_review: no findings

CI / Format (pull_request) Successful in 15s

Details

CI / Clippy (pull_request) Successful in 1m57s

Details

CI / Security Audit (pull_request) Successful in 26s

Details

CI / Test (pull_request) Successful in 2m59s

Details

CI / Mutation (pull_request) Has been skipped

Details

CI / CI Gate (pull_request) Successful in 1s

Details

eb2bfa918b

Add missing crate-level doc comments and public-item documentation to
eventcore-macros, eventcore-testing, eventcore-postgres, eventcore-sqlite,
and eventcore-fs. Fix pre-existing rustdoc errors in eventcore-types and
eventcore that caused `cargo doc` to fail.

- eventcore-macros: add module overview for #[derive(Command)]
- eventcore-testing: add module overview for all five testing modules
- eventcore-postgres: add module overview and doc comments on error/store types
- eventcore-sqlite: add module overview and doc comments on error/store types
- eventcore-fs: fix private-module links causing rustdoc errors
- eventcore-types: fix unresolved-link errors from bare [, ] in glob docs
- eventcore: fix private ExecutePipeline link and redundant link targets

`cargo doc --workspace --no-deps` now completes with zero errors.

auto-review approved these changes

2026-06-14 13:17:13 -07:00

auto-review left a comment

Walkthrough

eventcore-fs/src/lib.rs: Fixed private-module links that caused rustdoc errors.
eventcore-macros/src/lib.rs: Added comprehensive module-level documentation for the #[derive(Command)] macro.
eventcore-postgres/src/lib.rs: Added module-level documentation and detailed comments for error enums and store structs.
eventcore-sqlite/src/lib.rs: Added module-level documentation and detailed comments for error enums and store structs.
eventcore-testing/src/lib.rs: Added module-level documentation covering all testing modules.
eventcore-types/src/store.rs: Fixed unresolved-link errors in documentation.
eventcore/src/lib.rs: Fixed private link issues and redundant explicit link targets in documentation.

LLM usage and cost

Reasoning (gpt-4o) in=4211 out=471 cost=$0.028120
Cheap (gpt-4o-mini) in=668 out=43 cost=$0.000126
Estimated total USD: $0.028246 via https://api.openai.com and https://api.openai.com

The PR significantly improves the API documentation across multiple crates, addressing missing documentation and fixing rustdoc errors. The changes appear safe to merge, as they focus on documentation without altering functionality. ## Walkthrough - **eventcore-fs/src/lib.rs**: Fixed private-module links that caused rustdoc errors. - **eventcore-macros/src/lib.rs**: Added comprehensive module-level documentation for the `#[derive(Command)]` macro. - **eventcore-postgres/src/lib.rs**: Added module-level documentation and detailed comments for error enums and store structs. - **eventcore-sqlite/src/lib.rs**: Added module-level documentation and detailed comments for error enums and store structs. - **eventcore-testing/src/lib.rs**: Added module-level documentation covering all testing modules. - **eventcore-types/src/store.rs**: Fixed unresolved-link errors in documentation. - **eventcore/src/lib.rs**: Fixed private link issues and redundant explicit link targets in documentation. ## LLM usage and cost - Reasoning (gpt-4o) in=4211 out=471 cost=$0.028120 - Cheap (gpt-4o-mini) in=668 out=43 cost=$0.000126 Estimated total USD: $0.028246 via https://api.openai.com and https://api.openai.com

jwilger merged commit 50870da312 into main

2026-06-14 13:20:53 -07:00

jwilger referenced this pull request from a commit

2026-06-14 13:20:55 -07:00

docs: overhaul API documentation across all crates (#420)