anistark / anistark/waspy

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

Đang mở Phù hợp với người mới
#119 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
documentation good first issue priority-medium
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.