84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
---
|
||
id: release-crate-docs
|
||
name: Crate docs final pass — rustdoc across the four published crates
|
||
status: pending
|
||
depends_on: []
|
||
scope: moderate
|
||
risk: low
|
||
impact: component
|
||
level: implementation
|
||
tags: [wave-8, docs, rustdoc]
|
||
---
|
||
|
||
## Description
|
||
|
||
The plan's wave-8 "crate docs" item: the public-API rustdoc of the
|
||
four published crates (`alkstore`, `alkstore-sqlite`,
|
||
`alkstore-postgres`, `alkstore-mem`) gets its release pass. The crate
|
||
docs are load-bearing — core's doc text is part of the contract
|
||
artifact (ADR-001 §1; AGENTS.md: "core's docs are part of the
|
||
contract") and the engine crates' lib docs carry the ADR-016 honesty
|
||
postures — so this is an accuracy-and-completeness pass, not prose
|
||
polish.
|
||
|
||
1. **Build clean**: `cargo doc --no-deps` (workspace) zero warnings —
|
||
broken intra-doc links, ambiguous links, missing docs. Also
|
||
`RUSTDOCFLAGS="-D warnings" cargo doc --no-deps` as the recorded
|
||
gate posture.
|
||
2. **Missing-docs audit**: every public item (traits, trait methods,
|
||
types, variants, fields, functions — including the `#[doc(hidden)]`
|
||
re-exports the fuzz wave added at the three engine roots, which
|
||
must stay documented as fuzz/test-only surfaces) carries doc text;
|
||
gaps filled. Consider whether `#![deny(missing_docs)]` (or
|
||
`warn`) is warranted per crate — decide and record; adding it is
|
||
the enforcement posture, skipping it needs a reason.
|
||
3. **Accuracy spot-check against the specs**: core's trait/type doc
|
||
text read against `core-contract.md` (the docs are contract text —
|
||
a drift is a defect); each engine's lib-doc posture claims
|
||
(writer-parking, connection budget, honest-ephemeral, wasm subset)
|
||
read against `deployment.md` and the engine specs. The wave-6
|
||
gate's inline doc fixes are the precedent for the honesty standard.
|
||
4. **Crate-level `//!` docs**: each published crate's root module doc
|
||
names its posture, its ADR charter, and (for engines) its
|
||
deployment boundary — verify all four do, fill what's missing.
|
||
5. **Examples**: core's public surface has no doctest examples; decide
|
||
whether a minimal compile-checked example (a `MemStore` open +
|
||
one mechanism round-trip) belongs in the core or mem crate docs —
|
||
the honest-ephemeral engine is the zero-config one, so it is the
|
||
natural example carrier. Either land it or record the not-taken
|
||
call.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] `cargo doc --no-deps` (workspace) zero warnings; the
|
||
`-D warnings` doc gate posture recorded
|
||
- [ ] Missing-docs audit recorded (public items × 4 crates); gaps
|
||
filled; the `#![deny(missing_docs)]` decision made and recorded
|
||
- [ ] Core doc text spot-checked against core-contract.md; engine
|
||
lib-doc posture claims spot-checked against deployment.md —
|
||
drifts fixed or recorded
|
||
- [ ] The doc-hidden fuzz re-exports documented as fuzz/test-only at
|
||
all three engine roots
|
||
- [ ] The example decision made (landed or recorded not-taken)
|
||
- [ ] Workspace gates green (`cargo build`, `cargo test`, clippy
|
||
`-D warnings`, fmt)
|
||
|
||
## References
|
||
|
||
- docs/plans/implementation.md §Wave 8
|
||
- docs/architecture/core-contract.md (the contract the core docs must
|
||
match)
|
||
- docs/architecture/deployment.md (the matrix the engine posture docs
|
||
must match)
|
||
- docs/architecture/decisions/016-deployment-honesty.md (the honesty
|
||
carriers)
|
||
- docs/architecture/decisions/024-mem-engine.md §5 (the wasm identity
|
||
the mem crate docs carry)
|
||
|
||
## Notes
|
||
|
||
> To be filled by implementation agent
|
||
|
||
## Summary
|
||
|
||
> To be filled on completion |