search

dart-lang / core

This repository is home to core Dart packages.
https://pub.dev/publishers/dart.dev
BSD 3-Clause "New" or "Revised" License
13 stars 3 forks source link

DelegatingMap documention is misleading #609

Open jamesderlin opened 3 years ago

jamesderlin commented 3 years ago

The documentation for DelegatingMap.addAll states:

The operation is equivalent to doing this[key] = value for each key and associated value in other.

That led me to mistakenly believe that a class that derives from DelegatingMap could override operator []= and change the behavior of addAll (and addEntries, etc.) for free. Alas, no, dartdoc automatically copied that from the base Map.addAll documentation, and addAll simply calls addAll on the delegate. (This behavior makes DelegatingMap seem significantly less useful.)

The implementation shown in the DelegatingMap.addAll documentation also doesn't make this as obvious as it could be because the delegate is named _base instead of _delegate.

This probably applies to the other Delegating... classes from package:collection, but I haven't looked at them too carefully.

lrhn commented 3 years ago

Good point. The behavior is equivalent only to the default behavior of []=. The documentation should be rewritten.

jamesderlin commented 1 year ago

I realize now that I probably should have started from MapMixin instead, which has the behavior I expected. I get the ...Mixin and Delegating... classes mixed up. (Actually, I'm not sure that I was even aware until now that there were two sets of classes.)

I'll also note that the documentation for ListMixin mentions DelegatingList, but the DelegatingList documentation does not refer to ListMixin. Meanwhile there are no references in either direction for MapMixin/DelegatingMap nor for SetMixin/DelegatingSet. It'd be nice if each referenced the other and explained what the differences are.