docs: say that parameterised annotations are what give collections an element type
- 主要言語
- Rust
- スター
- 22
- フォーク
- 6
- 平均マージ
- 1日 3時間
- マージ済み PR(30日)
- 6
説明
## 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
コントリビューションガイド
調査の方向性
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.
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- python, rust
- 領域
- compilers, documentation
- issue の種類
- ドキュメント
- 難易度
- 1/5
- 見積もり時間
- 1〜3時間
- 活発さ
- 活発
- 明瞭さ
- 明確に書かれている
- 初心者へのやさしさ
- 88/100