Check user doc cycle counts against source of truth
- 主要語言
- Rust
- 星號
- 772
- 分支
- 352
- 平均合併
- 1 天 12 小時
- 30 天內合併 PR
- 93
描述
User docs repeat cycle counts by hand, so they can drift from the generated core library docs.
Current stale examples:
- `docs/src/user_docs/core_lib/collections.md` says `num_leaves_to_num_peaks` is 67 cycles. `crates/lib/core/docs/collections/mmr.md` says 32.
- `docs/src/user_docs/core_lib/collections.md` says `mmr::unpack` is `162 + 9 * extra_peak_pair`. `crates/lib/core/docs/collections/mmr.md` says `215 + 9 * extra_peak_pair`.
- `docs/src/user_docs/core_lib/crypto/hashes.md` appears stale for Poseidon2 `hash_words` compared with `crates/lib/core/docs/crypto/hashes/poseidon2.md`.
Add a check that fails when user-doc cycle text is out of sync.
Suggested shape:
- Add `scripts/check-user-doc-cycles.sh` and a small parser script.
- Run `MIDEN_BUILD_LIB_DOCS=1 cargo check -p miden-core-lib` first, so `crates/lib/core/docs/**/*.md` is fresh.
- Compare generated `Cycles:` entries against mapped entries in `docs/src/user_docs/core_lib/**/*.md`.
- Start with an explicit mapping file, not fuzzy matching.
- Report the user doc path, procedure, expected text, and actual text on mismatch.
Example mapping:
```toml
[[entry]]
user_doc = "docs/src/user_docs/core_lib/collections.md"
section = "Merkle Mountain Range"
procedure = "unpack"
generated_doc = "crates/lib/core/docs/collections/mmr.md"
generated_procedure = "unpack"
```
Assembly instruction docs need measured fixtures, since they do not have generated MASM docs as a source of truth. Add stable markers in the docs and measure small snippets with `clk`.
Example marker:
```md
```
Example fixture:
```toml
[[case]]
id = "u32popcnt"
doc = "docs/src/user_docs/assembly/u32_operations.md"
program = "begin clk push.7 u32popcnt drop clk swap sub end"
expected = "32 cycles"
```
----
A stronger long-term fix is to generate the core library user-doc reference tables from MASM comments, instead of only checking cycle strings.
The core library already has this source of truth:
- Source: `crates/lib/core/asm/**/*.masm`
- Generator: `crates/lib/core/build.rs`
- Generated docs: `crates/lib/core/docs/**/*.md`
The user docs could keep hand-written overview text, but import generated procedure tables or per-procedure fragments. Those fragments could live under `docs/src/generated/core_lib/**/*.md` and be rendered with a Docusaurus-friendly version of the existing core-lib doc renderer.
Then CI can regenerate the fragments and fail if `git diff -- docs/src/generated` is non-empty. This would catch stale inputs, outputs, panic notes, descriptions, formulas, and cycle counts.
Suggested boundary: generate reference blocks, not whole user-doc pages. Keep conceptual prose hand-written.
貢獻指南
評估
這個 Issue 還沒有評估資料。