0xMiden / 0xMiden/miden-vm

docs: clarify coverage of the comprehensive instruction reference

Aperta
#3,705 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Rust
Stelle
772
Fork
352
Merge medio
1g 12h
PR unite (30g)
93

Descrizione

The assembly instruction reference describes itself as a comprehensive reference for Miden Assembly instructions.

I compared the static instruction spellings registered in
`crates/assembly-syntax/src/parser/cst/instructions.rs` against
`docs/src/user_docs/assembly/instruction_reference.md`.

All 141 registered spellings are documented somewhere under the assembly user
docs, so this is not a case of entirely undocumented instructions. However,
the consolidated reference currently has no standalone entry for:

- `adv.has_mapkey`
- `dyncall`
- `dynexec`
- `eval_circuit`
- `fri_ext2fold4`
- `horner_eval_base`
- `horner_eval_ext`
- `reversew`
- `reversedw`

Eight of these do not occur in the reference at all. `reversew` is mentioned
inside other instruction descriptions, but does not have its own reference row.

The instructions are covered by specialized pages such as
`code_organization.md`, `cryptographic_operations.md`,
`stack_manipulation.md`, and `io_operations.md`. The gap is specifically
between those pages and the page presented as the comprehensive reference.

This appears separate from #3111 / #3262, which check cycle values for mapped
documentation rows but do not detect a registered instruction that has no row
in the consolidated reference.

Before working on this, could you clarify the intended scope?

1. Is `instruction_reference.md` expected to include advanced, dynamic,
advice-provider, and precompile instructions?
2. If yes, would a focused completeness update followed by a small
parser-to-reference coverage guard be the preferred direction?
3. If those instructions are intentionally kept only in specialized pages,
should the page wording and cross-links be narrowed instead?

I have not prepared a patch yet and would wait for assignment before starting.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.