search

google / guava

Google core libraries for Java
Apache License 2.0
50.22k stars 10.91k forks source link

Provide replacement for Ordering.explicit or update Ordering javadoc to unobsolete it #3864

Open anuraaga opened 4 years ago

anuraaga commented 4 years ago

An issue to bring light to a long-term TODO that should probably be fixed :)

Ordering documents itself as obsolete for Java 8+ users https://guava.dev/releases/snapshot-jre/api/docs/com/google/common/collect/Ordering.html "If you are using Java 8, this class is now obsolete. Most of its functionality is now provided by Stream and by Comparator itself, and the rest can now be found as static methods in our new Comparators class."

This statement isn't actually true though since there doesn't seem to be a replacement for Ordering.explicit in any of Stream, Comparator, or Comparators. The code seems to acknowledge this with a TODO

https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/Ordering.java#L217

While the number of TODOs in a codebase usually indicate its maturity, perhaps it's a good time to address this one ;)

If a replacement could be made quickly (just copy to Comparators?), that'd be nice. Otherwise, simply tweaking the javadoc to explain the situation so the code doesn't need to be read would be nice. That paragraph could have Note, there is no replacement for {@link #explicit} quite yet. added and / or the method javadocs for explicit could have something like Note, this method does not currently have a replacement in the JDK or {@link Comparators} yet..

If any of these options sounds reasonable, I'm happy to send a PR.

Without tweaking the Javadoc, readers will search around for this method in the three mentioned classes, with the disappointing conclusion of not actually finding it at best or forever wondering if they missed something at worst.

anuraaga commented 4 years ago

Also realized the paragraph in the javadoc in the JRE non-android version can be tweaked to reflect the fact that all guava users are using Java 8+ now.

kevinb9n commented 4 years ago

You're right that the class would be more ideally described as "mostly" obsolete.

oliviercailloux commented 3 years ago

Without tweaking the Javadoc, readers will search around for this method in the three mentioned classes, with the disappointing conclusion of not actually finding it at best or forever wondering if they missed something at worst.

… or be saved thanks to this post.