docs: fix stale and incomplete API doc comments #422

Merged

jwilger merged 3 commits from docs/api-doc-follow-up into main 2026-06-14 14:02:40 -07:00

Conversation 2 Commits 3 Files changed 2 +25 -9

jwilger commented 2026-06-14 13:54:43 -07:00

Owner

Copy link

Summary

Follow-up to PR #420 — two inaccuracies found in review:

• ExecutionResponse had a stale placeholder doc ("yet to be determined"). Replaced with accurate description of what the type represents and documented the attempts() method. Added ExecutionResponse to the module-level error-handling section of eventcore/src/lib.rs.
• eventcore-types module overview was incomplete — it omitted StreamPattern, StreamPrefix, EventFilter, EventPage, all projection traits (Projector, EventReader, CheckpointStore, ProjectorCoordinator), and BusinessRuleMessage.

Test plan

• cargo doc --workspace --no-deps still passes with zero errors
• All 275 tests pass

## Summary Follow-up to PR #420 — two inaccuracies found in review: - **`ExecutionResponse`** had a stale placeholder doc ("yet to be determined"). Replaced with accurate description of what the type represents and documented the `attempts()` method. Added `ExecutionResponse` to the module-level error-handling section of `eventcore/src/lib.rs`. - **`eventcore-types` module overview** was incomplete — it omitted `StreamPattern`, `StreamPrefix`, `EventFilter`, `EventPage`, all projection traits (`Projector`, `EventReader`, `CheckpointStore`, `ProjectorCoordinator`), and `BusinessRuleMessage`. ## Test plan - [x] `cargo doc --workspace --no-deps` still passes with zero errors - [x] All 275 tests pass

jwilger added 2 commits 2026-06-14 13:54:43 -07:00

docs: overhaul API documentation across all crates ... 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.

docs: fix stale and incomplete API doc comments ... 240d5327be

Follow-up to the documentation overhaul (PR #420):

- eventcore/src/lib.rs: replace stale 'yet to be determined' doc on
  ExecutionResponse with accurate description; document the attempts()
  method; add ExecutionResponse to the module-level error-handling section
- eventcore-types/src/lib.rs: expand module overview to accurately list
  all exported types including StreamPattern, StreamPrefix, EventFilter,
  EventPage, projection traits (Projector, EventReader, CheckpointStore,
  ProjectorCoordinator), and error types

auto-review approved these changes 2026-06-14 13:54:55 -07:00

Dismissed

auto-review left a comment

Copy link

This PR updates stale and incomplete API documentation across several modules, improving clarity and accuracy. The changes appear safe to merge as they only affect documentation and all tests pass.

Walkthrough

• eventcore-fs/src/lib.rs: Updated module map to use plain text instead of code formatting for section names.
• eventcore-macros/src/lib.rs: Added detailed documentation for procedural macros, including usage examples and requirements.
• eventcore-postgres/src/lib.rs: Introduced comprehensive documentation for the PostgreSQL backend, covering features and usage.
• eventcore-sqlite/src/lib.rs: Added documentation for the SQLite backend, highlighting its features and usage scenarios.
• eventcore-testing/src/lib.rs: Provided detailed descriptions of testing utilities and their modules.
• eventcore-types/src/lib.rs: Expanded the overview to include missing types and traits, improving module completeness.
• eventcore-types/src/store.rs: Corrected documentation to use code formatting for glob metacharacters.
• eventcore/src/lib.rs: Updated error handling and execution response documentation to reflect current functionality.

LLM usage and cost

• Reasoning (gpt-4o) in=4827 out=295 cost=$0.028560
• Cheap (gpt-4o-mini) in=477 out=68 cost=$0.000112
  Estimated total USD: $0.028672 via https://api.openai.com and https://api.openai.com

This PR updates stale and incomplete API documentation across several modules, improving clarity and accuracy. The changes appear safe to merge as they only affect documentation and all tests pass. ## Walkthrough - **eventcore-fs/src/lib.rs**: Updated module map to use plain text instead of code formatting for section names. - **eventcore-macros/src/lib.rs**: Added detailed documentation for procedural macros, including usage examples and requirements. - **eventcore-postgres/src/lib.rs**: Introduced comprehensive documentation for the PostgreSQL backend, covering features and usage. - **eventcore-sqlite/src/lib.rs**: Added documentation for the SQLite backend, highlighting its features and usage scenarios. - **eventcore-testing/src/lib.rs**: Provided detailed descriptions of testing utilities and their modules. - **eventcore-types/src/lib.rs**: Expanded the overview to include missing types and traits, improving module completeness. - **eventcore-types/src/store.rs**: Corrected documentation to use code formatting for glob metacharacters. - **eventcore/src/lib.rs**: Updated error handling and execution response documentation to reflect current functionality. ## LLM usage and cost - Reasoning (gpt-4o) in=4827 out=295 cost=$0.028560 - Cheap (gpt-4o-mini) in=477 out=68 cost=$0.000112 Estimated total USD: $0.028672 via https://api.openai.com and https://api.openai.com

jwilger added 1 commit 2026-06-14 13:59:03 -07:00

Merge remote-tracking branch 'origin/main' into docs/api-doc-follow-up db778e35a9

auto-review approved these changes 2026-06-14 13:59:14 -07:00

auto-review left a comment

Copy link

The pull request updates the API documentation by replacing stale placeholders and adding missing module overviews. The changes are documentation-only and do not affect the code logic, making it safe to merge.

Walkthrough

Δ since 240d532:

• Documentation Updates:
  • Updated ExecutionResponse documentation to replace stale placeholder text with accurate descriptions.
  • Added missing module overview for eventcore-types, including StreamPattern, StreamPrefix, EventFilter, EventPage, and various projection traits.

LLM usage and cost

• Reasoning (gpt-4o) in=35324 out=119 cost=$0.178405
• Cheap (gpt-4o-mini) in=477 out=49 cost=$0.000101
  Estimated total USD: $0.178506 via https://api.openai.com and https://api.openai.com

The pull request updates the API documentation by replacing stale placeholders and adding missing module overviews. The changes are documentation-only and do not affect the code logic, making it safe to merge. ## Walkthrough ### Δ since 240d532: - **Documentation Updates**: - Updated `ExecutionResponse` documentation to replace stale placeholder text with accurate descriptions. - Added missing module overview for `eventcore-types`, including `StreamPattern`, `StreamPrefix`, `EventFilter`, `EventPage`, and various projection traits. ## LLM usage and cost - Reasoning (gpt-4o) in=35324 out=119 cost=$0.178405 - Cheap (gpt-4o-mini) in=477 out=49 cost=$0.000101 Estimated total USD: $0.178506 via https://api.openai.com and https://api.openai.com

jwilger merged commit 5a2caeb242 into main 2026-06-14 14:02:40 -07:00

jwilger referenced this pull request from a commit 2026-06-14 14:02:42 -07:00

docs: fix stale and incomplete API doc comments (#422)

release-plz-bot referenced this pull request 2026-06-14 14:05:55 -07:00

chore(release): v1.0.1 #423

release-plz-bot referenced this pull request 2026-06-14 21:08:27 -07:00

chore(release): v2.0.0 #425

release-plz-bot referenced this pull request 2026-06-14 21:29:33 -07:00

chore(release): v1.0.1 #427

jwilger referenced this pull request from a commit 2026-06-15 10:46:19 -07:00

chore(release): v1.0.1

Sign in to join this conversation.

Reviewers

No reviewers

auto-review

Labels

Clear labels   

adr

Architecture Decision Record

  

automated

  

bug

Something isn't working

  

chore

Maintenance (audits, cleanup)

  

dependencies

  

documentation

Improvements or additions to documentation

  

enhancement

New feature or request

  

epic

Large feature with sub-issues

  

github-actions

  

P1-high

  

P2-medium

Default priority

  

P3-low

Polish, optimization

  

release

  

research

Investigation / spike

  

rust

  

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

help wanted

Need some help

  

invalid

Something is wrong

  

question

More information is needed

  

wontfix

This won't be fixed

No labels

adr

automated

bug

chore

dependencies

documentation

enhancement

epic

github-actions

P1-high

P2-medium

P3-low

release

research

rust

bug

duplicate

enhancement

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Slipstream/eventcore!422

No description provided.