Summary
-------

Describe operational semantics of `Objects.equals`.

Problem
-------

A buggy equals implementation on one of its arguments can cause `Objects.equals` to return unexpected results.

Solution
--------

Make the long-standing operational semantics of `Objects.equals` part of its specification.

Specification
-------------

    diff -r 7ab4310ed472 src/java.base/share/classes/java/util/Objects.java
    --- a/src/java.base/share/classes/java/util/Objects.java    Wed May 01 20:25:31 2019 -0700
    +++ b/src/java.base/share/classes/java/util/Objects.java    Thu May 02 14:41:06 2019 -0700
    @@ -62,10 +62,11 @@
          * Returns {@code true} if the arguments are equal to each other
          * and {@code false} otherwise.
          * Consequently, if both arguments are {@code null}, {@code true}
    -     * is returned and if exactly one argument is {@code null}, {@code
    -     * false} is returned.  Otherwise, equality is determined by using
    -     * the {@link Object#equals equals} method of the first
    -     * argument.
    +     * is returned.  Otherwise, if the first argument is not {@code
    +     * null}, equality is determined by calling the {@link
    +     * Object#equals equals} method of the first argument with the
    +     * second argument of this method. Otherwise, {@code false} is
    +     * returned.
          *
          * @param a an object
          * @param b an object to be compared with {@code a} for equality
    
    ...
    
        public static boolean equals(Object a, Object b) {
            return (a == b) || (a != null && a.equals(b));
        }