Rewrite Javadoc of RuleChain

The purpose of this rule is no longer the ordering of rules but it can
still be used for composing rules into a single rule. Therefore we
remove the deprecation.

Fixes #1614.

src/main/java/org/junit/rules/RuleChain.java

@@ -4,26 +4,34 @@
 import java.util.Collections;
 import java.util.List;
 
+import org.junit.Rule;
 import org.junit.runner.Description;
 import org.junit.runners.model.Statement;
 
 /**
- * The RuleChain rule allows ordering of TestRules. You create a
+ * The {@code RuleChain} can be used for creating composite rules. You create a
  * {@code RuleChain} with {@link #outerRule(TestRule)} and subsequent calls of
  * {@link #around(TestRule)}:
  *
  * <pre>
+ * public abstract class CompositeRules {
+ *   public static TestRule extendedLogging() {
+ *     return RuleChain.outerRule(new LoggingRule("outer rule"))
+ *                     .around(new LoggingRule("middle rule"))
+ *                     .around(new LoggingRule("inner rule"));
+ *   }
+ * }
+ * </pre>
+ *
+ * <pre>
  * public class UseRuleChain {
- * 	&#064;Rule
- * 	public RuleChain chain= RuleChain
- * 	                       .outerRule(new LoggingRule("outer rule"))
- * 	                       .around(new LoggingRule("middle rule"))
- * 	                       .around(new LoggingRule("inner rule"));
+ *   &#064;Rule
+ *   public final TestRule extendedLogging = CompositeRules.extendedLogging();
  *
- * 	&#064;Test
- * 	public void example() {
- * 		assertTrue(true);
- *     }
+ *   &#064;Test
+ *   public void example() {
+ *     assertTrue(true);
+ *   }
  * }
  * </pre>
  *
@@ -37,28 +45,16 @@
  * finished middle rule
  * finished outer rule
  * </pre>
- * 
- * {@code RuleChain} cannot be used to define the order of existing rules.
- * For example in the below snippet the LoggingRule {@code middle} would be
- * executed outside as well as inside the {@code RuleChain}:
  *
- * <pre>
- * &#064;Rule
- * public LoggingRule middle = new LoggingRule("middle rule");
- * 
- * &#064;Rule
- * public RuleChain chain = RuleChain
- *                          .outerRule(new LoggingRule("outer rule"))
- *                          .around(middle)
- *                          .around(new LoggingRule("inner rule"));
- * </pre>
+ * In older versions of JUnit (before 4.13) {@code RuleChain} was used for
+ * ordering rules. We recommend to not use it for this purpose anymore. You can
+ * use the attribute {@code order} of the annotation {@link Rule#order() Rule}
+ * or {@link org.junit.ClassRule#order() ClassRule} for ordering rules.
  *
- * @deprecated Since 4.13 ordering of rules can be naturally specified with an annotation attribute.
  * @see org.junit.Rule#order()
  * @see org.junit.ClassRule#order()
  * @since 4.10
  */
-@Deprecated
 public class RuleChain implements TestRule {
     private static final RuleChain EMPTY_CHAIN = new RuleChain(
             Collections.<TestRule>emptyList());