Please document (lack of) equality guarantees for ImmutableMap.values()

ImmutableMap already documents that values() iterates the values in the order that entries were added to the map. However, the return type is ImmutableCollection, which does not have any particular equality guarantees per se (it inherits the non-guarantees from Collection).

I would have assumed that for any two ImmutableMap instances that contained equal values added in the same order, values() would return collections that would compare equal. However, this does not appear to be guaranteed (and appears to definitely be incorrect for some implementations, like ImmutableMapValues, which have no equals() method).

Assuming no guarantees are intended, would it be reasonable to add a note to values() pointing out that — unlike entrySet() and keySet() — there is no guarantee that the collection returned from values() has a sensible equality implementation (and perhaps pointing at values().asList() as a (usually cheap) way to get a collection that does).

(I guess this applies to the values() methods in ImmutableMultimap, ImmutableSortedMap, and ImmutableTable too?)

[Meijuh]

I would like to note the importance of solving this issue. The following simple code already fails, without clear documentation why:

final ArrayListMultimap<String, String> alm1 = ArrayListMultimap.create();
final ArrayListMultimap<String, String> alm2 = ArrayListMultimap.create();
assert alm1.values().equals(alm2.values());

[malcolmr]

Good point about ErrorProne (this would be https://errorprone.info/bugpattern/UndefinedEquals, I assume?).

Worth noting that that check presently won’t trigger for ImmutableCollection, since it requires the receiver type to be exactly Collection (or Iterable, etc). I guess we could add it easily enough, though?

And yes, the “mostly this will work except where it doesn’t” aspect was the part that was troubling me here.

Would it be worth adding @Deprecated ImmutableCollection.equals() with a pointer to asList()? (Or is that only warranted for methods like ImmutableList.add() that are always an error?)