docs: say that parameterised annotations are what give collections an element type
- Ngôn ngữ chính
- Rust
- Star
- 22
- Fork
- 6
- Merge trung bình
- 1 ngày 3 giờ
- Pull request đã merge (30 ngày)
- 6
Mô tả
## Summary
`README.md` documents `List[T]`, `Dict[K,V]` and friends as supported type annotations, but does not say that the *parameterised* form is what makes the element type known, or what goes wrong when a bare `list` or `dict` is used instead. A reader who writes `-> list` gets a silently wrong answer with nothing pointing at the annotation.
This is the documentation half of #116, split out because it is small, self-contained, and needs no design decision. The inference half stays on #116.
## Current state
Bare builtin annotations map to collection types whose element type is `Unknown`: https://github.com/anistark/waspy/blob/d7dcbc4/src/ir/converter.rs#L965-L975
The consequence, from #116: a dict keyed on strings that came out of a `-> list` function does not deduplicate, because with `Unknown` on both sides the keys compare as raw words rather than by content.
`examples/text_report.py` already spells this out in its docstring, which is a good model for the wording: https://github.com/anistark/waspy/blob/d7dcbc4/examples/text_report.py
## Proposed change
Add a short note to the type-annotation section of `README.md`, and mirror it in `docs/`:
- Parameterised annotations (`List[str]`, `Dict[str, int]`) are what give the compiler an element type.
- A bare `list` or `dict` compiles, but its element type is unknown, and operations that depend on it (dict keys comparing by content, calling a string method on an element) will not behave as they do in CPython.
- Prefer the parameterised form for any collection whose elements are used.
## Acceptance criteria
- [ ] `README.md` says which annotation forms carry an element type and what is lost without one
- [ ] `docs/` carries the same statement, so the published site does not drift
- [ ] The wording names a concrete consequence rather than only stating a preference
## References
- #116, the inference half of the same gap
Hướng dẫn đóng góp
Hướng nghiên cứu
Start with the type-annotation section in README.md and locate its corresponding page under docs/; use examples/text_report.py as the wording reference and consult src/ir/converter.rs around lines 965-975 for the stated current behavior. Done means both documentation locations explain parameterised collection annotations, the consequence of bare list/dict, and why the parameterised form is preferred.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python, rust
- Lĩnh vực
- compilers, documentation
- Loại issue
- Tài liệu
- Độ khó
- 1/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 88/100