docs: clarify coverage of the comprehensive instruction reference
- 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
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