1 files changed, 35 insertions, 4 deletions
diff --git a/src/main/java/org/junit/Rule.java b/src/main/java/org/junit/Rule.java
index 711235c..9370e94 100644
--- a/src/main/java/org/junit/Rule.java
+++ b/src/main/java/org/junit/Rule.java
@@ -16,12 +16,14 @@ import java.lang.annotation.Target;
  * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods,
  * then the {@link Test} method, and finally any {@link After} methods,
  * throwing an exception if any of these fail.  If there are multiple
- * annotated {@link Rule}s on a class, they will be applied in order of fields first, then methods.
+ * annotated {@link Rule}s on a class, they will be applied in order of methods first, then fields.
  * However, if there are multiple fields (or methods) they will be applied in an order
  * that depends on your JVM's implementation of the reflection API, which is
  * undefined, in general. Rules defined by fields will always be applied
- * before Rules defined by methods. You can use a {@link org.junit.rules.RuleChain} if you want
- * to have control over the order in which the Rules are applied.
+ * after Rules defined by methods, i.e. the Statements returned by the former will
+ * be executed around those returned by the latter.
+ *
+ * <h3>Usage</h3>
  * <p>
  * For example, here is a test class that creates a temporary folder before
  * each test method, and deletes it after each:
@@ -61,10 +63,39 @@ import java.lang.annotation.Target;
  * For more information and more examples, see
  * {@link org.junit.rules.TestRule}.
  *
+ * <h3>Ordering</h3>
+ * <p>
+ * You can use {@link #order()} if you want to have control over the order in
+ * which the Rules are applied.
+ *
+ * <pre>
+ * public class ThreeRules {
+ *     &#064;Rule(order = 0)
+ *     public LoggingRule outer = new LoggingRule("outer rule");
+ *
+ *     &#064;Rule(order = 1)
+ *     public LoggingRule middle = new LoggingRule("middle rule");
+ *
+ *     &#064;Rule(order = 2)
+ *     public LoggingRule inner = new LoggingRule("inner rule");
+ *
+ *     // ...
+ * }
+ * </pre>
+ *
  * @since 4.7
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD})
 public @interface Rule {
 
-}
-\ No newline at end of file
+    int DEFAULT_ORDER = -1;
+
+    /**
+     * Specifies the order in which rules are applied. The rules with a higher value are inner.
+     *
+     * @since 4.13
+     */
+    int order() default DEFAULT_ORDER;
+
+}