8374953: Add note on about implicit state when comparing TypeMirrors

Reviewed-by: attila, vromero, jlahoda

Author: jddarcy

src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2026, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -120,6 +120,15 @@ public interface TypeMirror extends AnnotatedConstruct {
      * The results of {@code t1.equals(t2)} and
      * {@code Types.isSameType(t1, t2)} may differ.
      *
+     * @apiNote The identity of a {@code TypeMirror} involves implicit
+     * state not directly accessible from its methods, including state
+     * about the presence of unrelated types. {@code TypeMirror}
+     * objects created by different implementations of these
+     * interfaces should <i>not</i> be expected to compare as equal
+     * even if &quot;the same&quot; type is being modeled; this is
+     * analogous to the inequality of {@code Class} objects for the
+     * same class file loaded through different class loaders.
+     *
      * @param obj  the object to be compared with this type
      * @return {@code true} if the specified object is equal to this one
      */

src/java.compiler/share/classes/javax/lang/model/util/Types.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2026, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -106,6 +106,15 @@ public interface Types {
      * {@code TypeMirror} objects can have different annotations and
      * still be considered the same.
      *
+     * @apiNote The identity of a {@code TypeMirror} involves implicit
+     * state not directly accessible from its methods, including state
+     * about the presence of unrelated types. {@code TypeMirror}
+     * objects created by different implementations of these
+     * interfaces should <i>not</i> be expected to compare as equal
+     * even if &quot;the same&quot; type is being modeled; this is
+     * analogous to the inequality of {@code Class} objects for the
+     * same class file loaded through different class loaders.
+     *
      * @param t1  the first type
      * @param t2  the second type
      * @return {@code true} if and only if the two types are the same