Revise Javadoc for PropertyAccessor & IndexAccessor regarding ordering

Closes gh-33862

Author: sbrannen

spring-expression/src/main/java/org/springframework/expression/IndexAccessor.java

@@ -26,21 +26,14 @@
  * structure. Implementors are therefore free to access indexed values any way
  * they deem appropriate.
  *
- * <p>An index accessor can optionally specify an array of target classes for
- * which it should be called. However, if it returns {@code null} or an empty
- * array from {@link #getSpecificTargetClasses()}, it will be called for all
- * indexing operations and given a chance to determine if it can read from or
- * write to the indexed structure.
- *
- * <p>Index accessors are considered to be ordered, and each will be called in
- * turn. The only rule that affects the call order is that any index accessor
- * which specifies explicit support for the target class via
- * {@link #getSpecificTargetClasses()} will be called first, before other
- * generic index accessors.
+ * <p>An index accessor can specify an array of
+ * {@linkplain #getSpecificTargetClasses() target classes} for which it should be
+ * called. See {@link TargetedAccessor} for details.
  *
  * @author Jackmiking Lee
  * @author Sam Brannen
  * @since 6.2
+ * @see TargetedAccessor
  * @see PropertyAccessor
  */
 public interface IndexAccessor extends TargetedAccessor {

spring-expression/src/main/java/org/springframework/expression/PropertyAccessor.java

@@ -26,19 +26,13 @@
  * Implementors are therefore free to access properties directly via fields,
  * through getters, or in any other way they deem appropriate.
  *
- * <p>A property accessor can optionally specify an array of target classes for
- * which it should be called. However, if it returns {@code null} from
- * {@link #getSpecificTargetClasses()}, it will be called for all property
- * references and given a chance to determine if it can read or write them.
- *
- * <p>Property accessors are considered to be ordered, and each will be called in
- * turn. The only rule that affects the call order is that any property accessor
- * which specifies explicit support for the target class via
- * {@link #getSpecificTargetClasses()} will be called first, before the generic
- * property accessors.
+ * <p>A property accessor can specify an array of
+ * {@linkplain #getSpecificTargetClasses() target classes} for which it should be
+ * called. See {@link TargetedAccessor} for details.
  *
  * @author Andy Clement
  * @since 3.0
+ * @see TargetedAccessor
  * @see IndexAccessor
  */
 public interface PropertyAccessor extends TargetedAccessor {

spring-expression/src/main/java/org/springframework/expression/TargetedAccessor.java

@@ -31,9 +31,11 @@
  *
  * <p>Targeted accessors are considered to be ordered, and each will be called
  * in turn. The only rule that affects the call order is that any accessor which
- * specifies explicit support for a given target class via
+ * specifies explicit support for a given target type via
  * {@link #getSpecificTargetClasses()} will be called first, before other generic
- * accessors that do not specify explicit support for the given target class.
+ * accessors that do not specify support for explicit target types. In addition,
+ * accessors that support the exact target type will be called before accessors
+ * that support a supertype of the target type.
  *
  * @author Sam Brannen
  * @since 6.2

spring-expression/src/main/java/org/springframework/expression/spel/ast/AstUtils.java

@@ -55,20 +55,23 @@ static <T extends TargetedAccessor> List<T> getAccessorsToTry(
 	/**
 	 * Determine the set of accessors that should be used to try to access an
 	 * element on the specified target type.
-	 * <p>The accessors are considered to be in an ordered list; however, in the
-	 * returned list any accessors that are exact matches for the input target
-	 * type (as opposed to 'generic' accessors that could work for any type) are
-	 * placed at the start of the list. In addition, if there are specific
-	 * accessors that exactly name the class in question and accessors that name
-	 * a specific class which is a supertype of the class in question, the latter
-	 * are put at the end of the specific accessors set and will be tried after
-	 * exactly matching accessors but before generic accessors.
+	 * <p>The supplied accessors are considered to be in an ordered list; however,
+	 * in the returned list any accessors that are exact matches for the supplied
+	 * target type are placed at the start of the list (as opposed to 'generic'
+	 * accessors that could work for any target type). In addition, if there are
+	 * accessors that claim support for the exact target type as well as accessors
+	 * that claim support for a supertype of the target type, the latter are placed
+	 * at the end of the specific accessors set and will be tried after exactly
+	 * matching accessors but before generic accessors.
+	 * <p>Only matching accessors and generic accessors will be included in the
+	 * returned list.
 	 * @param targetType the type upon which element access is being attempted
 	 * @param accessors the list of element accessors to process
 	 * @return a list of accessors that should be tried in order to access the
 	 * element on the specified target type, or an empty list if no suitable
 	 * accessor could be found
 	 * @since 6.2
+	 * @see TargetedAccessor#getSpecificTargetClasses()
 	 */
 	static <T extends TargetedAccessor> List<T> getAccessorsToTry(
 			@Nullable Class<?> targetType, List<T> accessors) {