Summary

Improve javax.lang.model.util.Elements docs by using @apiNote to clarify the behavior of the overrides method.

Problem

The current implementation of javax.lang.model.Elements.overrides() does not check the return type of the method. This can be confusing and users may mistakenly assume that Elements.overrides performs the same checks as the compiler.

Solution

Add an @apiNote in javax.lang.model.Elements to clarify the scope of the override checks.

Specification

In the description of overrides(ExecutableElement, ExecutableElement, TypeElement)

diff --git a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
index 7f0b493572e0d..35da7563b12b0 100644
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
@@ -778,6 +778,12 @@ default TypeElement getOutermostTypeElement(Element e) {
      *                           elements.getTypeElement("I"));
      * }
      *
+     * @apiNote The notion of overriding, by itself, does not involve the
+     * method's return type, listed exceptions, or, to some extent, access
+     * modifiers. These are additional requirements checked by the compiler;
+     * see JLS {@jls 8.4.8.3} for details. An implementation may choose not
+     * to check the additional requirements under some conditions.
+     *
      *