Add schema-first API docs drift detector (xtask check-docs)
Documentation.md's Lua API and IPC protocol sections are hand-written prose and have drifted from the actual bread.* binding / IPC method surface before. This adds a checked-in registry (api-schema.toml) of every current Lua binding and IPC method, plus a new xtask crate (`cargo run -p xtask -- check-docs`) that cross-checks it against breadd/src/lua/mod.rs, breadd/src/ipc/mod.rs, and Documentation.md itself, failing loudly on any mismatch. It's a drift detector, not a doc generator — Documentation.md's prose is untouched except for one genuine gap the bootstrap surfaced: bread.hyprland.eval had no mention anywhere in the docs, now given a one-line example alongside its siblings. CONTRIBUTING.md documents the resulting contributor workflow.
This commit is contained in:
parent
96639516b1
commit
c5e871694a
7 changed files with 1152 additions and 0 deletions
|
|
@ -67,6 +67,24 @@ cargo build --release --workspace
|
|||
cargo test --release --workspace
|
||||
```
|
||||
|
||||
### Keeping the API docs honest
|
||||
|
||||
`Documentation.md`'s Lua API and IPC protocol sections are hand-written and
|
||||
have drifted from the actual code before — there's a checked-in registry,
|
||||
`api-schema.toml`, plus an `xtask` checker that catches it happening again.
|
||||
|
||||
Whenever you add, rename, or remove a `bread.*` Lua binding
|
||||
(`breadd/src/lua/mod.rs`) or an IPC method (`breadd/src/ipc/mod.rs`):
|
||||
|
||||
1. Add/update/remove its entry in `api-schema.toml` to match.
|
||||
2. Add/update the corresponding section in `Documentation.md` (a
|
||||
`#### bread.<name>` heading for a Lua binding, or a row in the IPC
|
||||
Methods table for an IPC method).
|
||||
3. Run `cargo run -p xtask -- check-docs` before committing. It fails with
|
||||
a non-zero exit and a list of exactly what's out of sync — added but
|
||||
undocumented, stale in the schema, or missing a doc heading/row — if
|
||||
`api-schema.toml`, the code, and `Documentation.md` don't all agree.
|
||||
|
||||
## CI
|
||||
|
||||
- `dev-release.yml` — triggered on push to `main`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue