docs(hooks): clarify manual-wiring requirement; track auto-invocation in #127#128
Merged
Conversation
…ation in #127 `#[entity(hooks)]` emits the `{Entity}Hooks` trait but the generated `impl {Entity}Repository for sqlx::PgPool` never calls it. Users reading the docs reasonably expect the generator to wire the two together — they don't, because Rust's orphan rule blocks user crates from writing `impl …Hooks for PgPool` (both type and trait are foreign). Until full auto-invocation lands, document the actual contract: - `crates/entity-derive-impl/src/entity/hooks.rs` module docs grow a prominent "Status" block explaining the manual-wiring requirement and linking the tracking issue (#127). The usage example is rewritten so it no longer suggests `impl UserHooks for MyRepo(PgPool)` (orphan-ruled out) — the recommended pattern is a service struct that owns the pool. - The generated trait's doc comment carries the same "Invocation is manual" warning so users hovering on the trait in their IDE see it. - `README.md` features table softens the "Lifecycle Hooks" bullet to reflect the current opt-in / manual-fire contract and links to #127. - `examples/hooks/src/main.rs` gains a top-of-file banner naming the pattern explicitly so readers don't waste time looking for the missing auto-wiring. No runtime behavior change. The follow-up issue #127 holds the design discussion for the actual fix (a `{Entity}Repo<H>` wrapper struct that threads hook calls through every CRUD method). Closes #126
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #126
Follow-up RFC: #127
Summary
`#[entity(hooks)]` emits the `{Entity}Hooks` trait. The current docs imply that generated CRUD will call the hooks; it doesn't, and orphan rule prevents users from making it call them with a local impl. Honest documentation fix while #127 designs the wrapper-struct architecture.
Changes
No runtime behavior change.
Out of scope
`#127` tracks the real fix: `{Entity}Repo` wrapper that threads hook calls through every CRUD method. That's a minor-version bump and deserves a separate PR.
Test plan