docs: say that parameterised annotations are what give collections an element type
- Lenguaje dominante
- Rust
- Estrellas
- 22
- Forks
- 6
- Merge medio
- 1 d 3 h
- PR fusionados (30 d)
- 6
Descripción
## 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
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.