0xMiden / 0xMiden/miden-vm

docs: clarify coverage of the comprehensive instruction reference

Đang mở Phù hợp với người mới
#3,705 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Rust
Star
772
Fork
352
Merge trung bình
1 ngày 7 giờ
Pull request đã merge (30 ngày)
84

Mô tả

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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Compare the list of instruction spellings in crates/assembly-syntax/src/parser/cst/instructions.rs against the entries in docs/src/user_docs/assembly/instruction_reference.md. Identify the missing instructions and check if they are documented in other specialized pages. Determine the intended scope based on maintainer feedback, then either add missing rows to the reference or adjust the page's introductory wording and cross-links.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
rust
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
65/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.