Document that OrderComparator honors PriorityOrdered

Prior to this commit, it was not clear that OrderComparator sorts
PriorityOrdered objects with higher priority than plain Ordered objects.

Author: sbrannen

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 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.
@@ -27,6 +27,10 @@
  * {@link Comparator} implementation for {@link Ordered} objects, sorting
  * by order value ascending, respectively by priority descending.
  *
+ * <h3>{@code PriorityOrdered} Objects</h3>
+ * <p>{@link PriorityOrdered} objects will be sorted with higher priority than
+ * <em>plain</em> {@code Ordered} objects.
+ *
  * <h3>Same Order Objects</h3>
  * <p>Objects that have the same order value will be sorted with arbitrary
  * ordering with respect to other objects with the same order value.
@@ -41,6 +45,7 @@
  * @author Sam Brannen
  * @since 07.04.2003
  * @see Ordered
+ * @see PriorityOrdered
  * @see org.springframework.core.annotation.AnnotationAwareOrderComparator
  * @see java.util.List#sort(java.util.Comparator)
  * @see java.util.Arrays#sort(Object[], java.util.Comparator)