anistark / anistark/waspy

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

オープン 初心者向け
#119 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation good first issue priority-medium
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。