8029909: Clarify equals/hashcode behavior for java.time types

Summary: Document the behavior of equals and hashcode in java.time.chrono date types
Reviewed-by: sherman, scolebourne

src/share/classes/java/time/chrono/HijrahDate.java

@@ -608,6 +608,48 @@ public final class HijrahDate
         return getChronology().period(Math.toIntExact(years), months, days);
     }
 
+    //-------------------------------------------------------------------------
+    /**
+     * Compares this date to another date, including the chronology.
+     * <p>
+     * Compares this {@code HijrahDate} with another ensuring that the date is the same.
+     * <p>
+     * Only objects of type {@code HijrahDate} are compared, other types return false.
+     * To compare the dates of two {@code TemporalAccessor} instances, including dates
+     * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
+     *
+     * @param obj  the object to check, null returns false
+     * @return true if this is equal to the other date and the Chronologies are equal
+     */
+    @Override  // override for performance
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj instanceof HijrahDate) {
+            HijrahDate otherDate = (HijrahDate) obj;
+            return prolepticYear == otherDate.prolepticYear
+                && this.monthOfYear == otherDate.monthOfYear
+                && this.dayOfMonth == otherDate.dayOfMonth
+                && getChronology().equals(otherDate.getChronology());
+        }
+        return false;
+    }
+
+    /**
+     * A hash code for this date.
+     *
+     * @return a suitable hash code based only on the Chronology and the date
+     */
+    @Override  // override for performance
+    public int hashCode() {
+        int yearValue = prolepticYear;
+        int monthValue = monthOfYear;
+        int dayValue = dayOfMonth;
+        return getChronology().getId().hashCode() ^ (yearValue & 0xFFFFF800)
+                ^ ((yearValue << 11) + (monthValue << 6) + (dayValue));
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Defend against malicious streams.

src/share/classes/java/time/chrono/JapaneseDate.java

@@ -678,6 +678,18 @@ public final class JapaneseDate
     }
 
     //-------------------------------------------------------------------------
+    /**
+     * Compares this date to another date, including the chronology.
+     * <p>
+     * Compares this {@code JapaneseDate} with another ensuring that the date is the same.
+     * <p>
+     * Only objects of type {@code JapaneseDate} are compared, other types return false.
+     * To compare the dates of two {@code TemporalAccessor} instances, including dates
+     * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
+     *
+     * @param obj  the object to check, null returns false
+     * @return true if this is equal to the other date
+     */
     @Override  // override for performance
     public boolean equals(Object obj) {
         if (this == obj) {
@@ -690,6 +702,11 @@ public final class JapaneseDate
         return false;
     }
 
+    /**
+     * A hash code for this date.
+     *
+     * @return a suitable hash code based only on the Chronology and the date
+     */
     @Override  // override for performance
     public int hashCode() {
         return getChronology().getId().hashCode() ^ isoDate.hashCode();

src/share/classes/java/time/chrono/MinguoDate.java

@@ -440,6 +440,18 @@ public final class MinguoDate
     }
 
     //-------------------------------------------------------------------------
+    /**
+     * Compares this date to another date, including the chronology.
+     * <p>
+     * Compares this {@code MinguoDate} with another ensuring that the date is the same.
+     * <p>
+     * Only objects of type {@code MinguoDate} are compared, other types return false.
+     * To compare the dates of two {@code TemporalAccessor} instances, including dates
+     * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
+     *
+     * @param obj  the object to check, null returns false
+     * @return true if this is equal to the other date
+     */
     @Override  // override for performance
     public boolean equals(Object obj) {
         if (this == obj) {
@@ -452,6 +464,11 @@ public final class MinguoDate
         return false;
     }
 
+    /**
+     * A hash code for this date.
+     *
+     * @return a suitable hash code based only on the Chronology and the date
+     */
     @Override  // override for performance
     public int hashCode() {
         return getChronology().getId().hashCode() ^ isoDate.hashCode();

src/share/classes/java/time/chrono/ThaiBuddhistDate.java

@@ -440,6 +440,18 @@ public final class ThaiBuddhistDate
     }
 
     //-------------------------------------------------------------------------
+    /**
+     * Compares this date to another date, including the chronology.
+     * <p>
+     * Compares this {@code ThaiBuddhistDate} with another ensuring that the date is the same.
+     * <p>
+     * Only objects of type {@code ThaiBuddhistDate} are compared, other types return false.
+     * To compare the dates of two {@code TemporalAccessor} instances, including dates
+     * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
+     *
+     * @param obj  the object to check, null returns false
+     * @return true if this is equal to the other date
+     */
     @Override  // override for performance
     public boolean equals(Object obj) {
         if (this == obj) {
@@ -452,6 +464,11 @@ public final class ThaiBuddhistDate
         return false;
     }
 
+    /**
+     * A hash code for this date.
+     *
+     * @return a suitable hash code based only on the Chronology and the date
+     */
     @Override  // override for performance
     public int hashCode() {
         return getChronology().getId().hashCode() ^ isoDate.hashCode();