Document that Ordered is not supported for @ControllerAdvice beans

Closes gh-23172

spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 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.
@@ -32,31 +32,29 @@
  * {@link ModelAttribute @ModelAttribute} methods to be shared across
  * multiple {@code @Controller} classes.
  *
- * <p>Classes with {@code @ControllerAdvice} can be declared explicitly as Spring
- * beans or auto-detected via classpath scanning. All such beans are sorted via
- * {@link org.springframework.core.annotation.AnnotationAwareOrderComparator
- * AnnotationAwareOrderComparator}, i.e. based on
- * {@link org.springframework.core.annotation.Order @Order} and
- * {@link org.springframework.core.Ordered Ordered}, and applied in that order
- * at runtime. For handling exceptions, an {@code @ExceptionHandler} will be
- * picked on the first advice with a matching exception handler method. For
- * model attributes and {@code InitBinder} initialization, {@code @ModelAttribute}
- * and {@code @InitBinder} methods will also follow {@code @ControllerAdvice} order.
+ * <p>Classes annotated with {@code @ControllerAdvice} can be declared explicitly
+ * as Spring beans or auto-detected via classpath scanning. All such beans are
+ * sorted based on {@link org.springframework.core.annotation.Order @Order}
+ * semantics and applied in that order at runtime. For handling exceptions, an
+ * {@code @ExceptionHandler} will be picked on the first advice with a matching
+ * exception handler method. For model attributes and {@code InitBinder}
+ * initialization, {@code @ModelAttribute} and {@code @InitBinder} methods will
+ * also follow {@code @ControllerAdvice} order.
  *
  * <p>Note: For {@code @ExceptionHandler} methods, a root exception match will be
  * preferred to just matching a cause of the current exception, among the handler
  * methods of a particular advice bean. However, a cause match on a higher-priority
- * advice will still be preferred to a any match (whether root or cause level)
+ * advice will still be preferred over any match (whether root or cause level)
  * on a lower-priority advice bean. As a consequence, please declare your primary
- * root exception mappings on a prioritized advice bean with a corresponding order!
+ * root exception mappings on a prioritized advice bean with a corresponding order.
  *
  * <p>By default the methods in an {@code @ControllerAdvice} apply globally to
- * all Controllers. Use selectors {@link #annotations()},
- * {@link #basePackageClasses()}, and {@link #basePackages()} (or its alias
- * {@link #value()}) to define a more narrow subset of targeted Controllers.
- * If multiple selectors are declared, OR logic is applied, meaning selected
- * Controllers should match at least one selector. Note that selector checks
- * are performed at runtime and so adding many selectors may negatively impact
+ * all controllers. Use selectors such as {@link #annotations},
+ * {@link #basePackageClasses}, and {@link #basePackages} (or its alias
+ * {@link #value}) to define a more narrow subset of targeted controllers.
+ * If multiple selectors are declared, {@code OR} logic is applied, meaning selected
+ * controllers should match at least one selector. Note that selector checks
+ * are performed at runtime, so adding many selectors may negatively impact
  * performance and add complexity.
  *
  * @author Rossen Stoyanchev