Document execution order and wrapping behavior

Issue: #1620

Author: marcphilipp

junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java

@@ -38,7 +38,7 @@
  * methods may optionally declare parameters to be resolved by
  * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}.
  *
- * <h3>Inheritance</h3>
+ * <h3>Inheritance and Execution Order</h3>
  *
  * <p>{@code @BeforeAll} methods are inherited from superclasses as long as
  * they are not <em>hidden</em> or <em>overridden</em>. Furthermore,
@@ -50,6 +50,24 @@
  * and {@code @BeforeAll} methods from an interface will be executed before
  * {@code @BeforeAll} methods in the class that implements the interface.
  *
+ * <p>JUnit Jupiter does not guarantee the execution order of multiple
+ * {@code @BeforeAll} methods that are declared within a single test class or
+ * test interface. While it may at times appear that these methods are invoked
+ * in alphabetical order, they are in fact sorted using an algorithm that is
+ * deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @BeforeAll} methods are in no way linked to
+ * {@code @AfterAll} methods, i.e. there are no guarantees with regard to their
+ * wrapping behavior. For example, given two {@code @BeforeAll} methods
+ * {@code createA()} and {@code createB()} as well as two {@code @AfterAll}
+ * methods {@code destroyA()} and {@code destroyB()}, the order in which the
+ * {@code @BeforeAll} methods are executed (e.g. {@code createA()} before
+ * {@code createB()}) does not imply any order for the seemingly corresponding
+ * {@code @AfterAll} methods: (e.g. {@code destroyA()} might be called before
+ * <em>or</em> after {@code destroyB()}). Thus, the JUnit Team recommends that
+ * developers declare at most one {@code @BeforeAll}/{@code @AfterAll} method
+ * per test class/interface unless there are no dependencies between them.
+ *
  * <h3>Composition</h3>
  *
  * <p>{@code @BeforeAll} may be used as a meta-annotation in order to create