anistark / anistark/waspy

docs: say that parameterised annotations are what give collections an element type

Abierto
#119 0 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation good first issue priority-medium
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.