Documentation for HashMap's FromIterator with duplicate keys in the iterator

[jrose-signal]

Location

HashMap

Summary

HashMap implements FromIterator and Extend, but does not document what happens if there are duplicate keys in the iterator. The documentation for Extend does say "When extending a collection with an already existing key, that entry is updated", but

1. that isn't visible anywhere on the HashMap page,
2. FromIterator doesn't have to be implemented using Extend (though HashMap's is), and
3. that still doesn't specify behavior for duplicate keys in the iterator itself.

The current implementation silently takes the last value in the iterator, which is useful behavior and could easily be justified by saying "collection.extend(a).extend(b) should always be equivalent to collection.extend(a.chain(b))", but technically that isn't written down anywhere.

[NoraCodes]

✋ I'd like to tackle this if that's okay. Does it seem more appropriate to put this documentation on HashMap (in which case it could have a doctest to demonstrate the behavior), or on Extend (as you suggested), or both?

[jrose-signal]

I suspect there's a guiding principle that I don't know as a mere consumer of the documentation, but I at least don't want FromIterator to be forgotten here.