amaranth-lang / amaranth

A modern hardware definition language and toolchain based on Python
https://amaranth-lang.org/docs/amaranth/
BSD 2-Clause "Simplified" License
1.56k stars 174 forks source link

Clarify documentation on the module usage in `wiring.connect()` #1509

Open 5aji opened 1 month ago

5aji commented 1 month ago

The first argument to connect() is the module that the connections should be added to, but the documentation doesn't state this clearly. It becomes clear once you understand it (the connections must be added to something, and the documentation shows it later) but it tripped me up since I was mentally primed to other constructs that operate on a Module directly (If, FSM, .next etc).

https://github.com/amaranth-lang/amaranth/blob/f20f04277225fe714054472e3d6daf930a9b12ef/amaranth/lib/wiring.py#L1358-L1402

whitequark commented 1 month ago

The first argument to connect() is the module that the connections should be added to, but the documentation doesn't state this clearly.

I think it does in the guide section, but we should probably just expand the error message to guide to the correct usage, in this case.