Clarify semantics of the PriorityOrdered interface

This commit clarifies the semantics of the PriorityOrdered interface
with respect to sorting sets of objects containing both PriorityOrdered
and plain Ordered objects.

Closes gh-23187

Author: sbrannen

spring-core/src/main/java/org/springframework/core/PriorityOrdered.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,14 +18,19 @@
 
 /**
  * Extension of the {@link Ordered} interface, expressing a <em>priority</em>
- * ordering: order values expressed by {@code PriorityOrdered} objects
- * always apply before same order values expressed by <em>plain</em>
- * {@link Ordered} objects.
+ * ordering: {@code PriorityOrdered} objects are always applied before
+ * <em>plain</em> {@link Ordered} objects regardless of their order values.
  *
- * <p>This is primarily a special-purpose interface, used for objects where
- * it is particularly important to recognize <em>prioritized</em> objects
- * first, without even obtaining the remaining objects. A typical example:
- * prioritized post-processors in a Spring
+ * <p>When sorting a set of {@code Ordered} objects, {@code PriorityOrdered}
+ * objects and <em>plain</em> {@code Ordered} objects are effectively treated as
+ * two separate subsets, with the set of {@code PriorityOrdered} objects preceding
+ * the set of <em>plain</em> {@code Ordered} objects and with relative
+ * ordering applied within those subsets.
+ *
+ * <p>This is primarily a special-purpose interface, used within the framework
+ * itself for objects where it is particularly important to recognize
+ * <em>prioritized</em> objects first, potentially without even obtaining the
+ * remaining objects. A typical example: prioritized post-processors in a Spring
  * {@link org.springframework.context.ApplicationContext}.
  *
  * <p>Note: {@code PriorityOrdered} post-processor beans are initialized in
@@ -34,10 +39,10 @@
  * beans which do not require eager initialization for type matching.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 2.5
  * @see org.springframework.beans.factory.config.PropertyOverrideConfigurer
  * @see org.springframework.beans.factory.config.PropertyPlaceholderConfigurer
  */
 public interface PriorityOrdered extends Ordered {
-
 }