Sdk: Explain that List.== does not compare contents, link to collections.ListEquality

[mleonhard]

I had difficulty finding out how to compare the contents of two List objects. My first stop was the List.== operator:
https://api.dartlang.org/stable/2.3.2/dart-core/List-class.html#operators
That page links to Object.== operator. I spent 15 minutes finding the answer. How about updating the docs to helpfully state that List.== does not compare contents, but this can be done with the collections.ListEquality class?

[MetalDent]

Hi, is anyone working on this issue?

[mraleph]

@MetalDent It's not assigned to anybody, which means nobody is working on it.

[MetalDent]

@mraleph okay. Can I work on this then?

[mraleph]

@lrhn Lasse any opinions about this issue? What is the best way people could be guided towards proper ways to do deep comparison?

[lrhn]

The best approach is probably to add an abstract operator== on List (and Set, Map and Queue) and document that a list, by default (that is, unless a subtype says something else) does not compare elements, and then refer to Object.operator== and say that it simply compares the identity of the lists.

Should it be on Iterable as well? It seems that one doesn't surprise people as much.

[mraleph]

@MetalDent do you think you've gotten enough guidance from @lrhn reply above to start working on it (if you want)?

[MetalDent]

@mraleph okay, in which file will this go?

[mraleph]

List class is defined here https://github.com/dart-lang/sdk/blob/master/sdk/lib/core/list.dart

[MetalDent]

@mraleph but don't you think we should change the description of operator == in https://api.dartlang.org/stable/2.3.2/dart-core/List-class.html#operators? That under normal situations it doesn't compare the list?

[mraleph]

@MetalDent that file is autogenerated from the file I pointed you to. So if you add

class List<E> {
  /// Something something something
  operator == (Object other); 
}

that would affect the documentation file you are pointing to.

[mleonhard]

The docs now state:
https://api.dart.dev/stable/2.8.4/dart-core/List/operator_equals.html

Whether this list is equal to other.

Lists are, by default, only equal to themselves. Even if other is also a list, the equality comparison does not compare the elements of the two lists.

I expect that most coders looking up List.== are actually trying to compare list contents. How about pointing them to collections.ListEquality?

[natebosch]

@lrhn - do you have concerns about linking to dartdoc for package:collection from the SDK docs?

[lrhn]

Slight concerns. It means that the platform library documentation can get out of date if someone changes the package.
In this particular case, we own the package, and are in a position to recognize the change.

Would we link to a particular version of the package docs? If so, then that problem is moot, since that version should be stable, even if we publish breaking versions later (with proper major version increments).

[natebosch]

It means that the platform library documentation can get out of date if someone changes the package.
In this particular case, we own the package, and are in a position to recognize the change.

I think the risk is low (so long as we aren't too detailed). We likely won't remove things like ListEquality so linking to the class overall should be stable. Even if we do remove or rename it, I think the impact is fairly low and the situation is still mildly better than it is today - the user would follow a broken link and (hopefully) file an issue for us, but _wouldn't_ be left in the dark about whether there is some solution or whether they need to write their own.

Would we link to a particular version of the package docs?

We could, although I'm not sure we'd want to.