0xMiden / 0xMiden/miden-vm

Check user doc cycle counts against source of truth

未關閉
#3,111 2 則留言 0 個 reaction 已指派 1 人 已被 @crazywriter1 認領 在 GitHub 檢視
documentation tests
主要語言
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 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。