Document method and field inheritance semantics

See junit-team#3553

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -156,6 +156,16 @@ using the `@Order` annotation. See the <<extensions-registration-programmatic-or
 Extension Registration Order>> tip for `@RegisterExtension` fields for details.
 ====
 
+[NOTE]
+.Extension Inheritance
+====
+Extensions registered declaratively via `@ExtendWith` on fields in superclasses will be
+inherited.
+
+See the <<extensions-registration-programmatic-inheritance, Extension Inheritance>> note
+for `@RegisterExtension` fields for details.
+====
+
 NOTE: `@ExtendWith` fields may be either `static` or non-static. The documentation on
 <<extensions-registration-programmatic-static-fields, Static Fields>> and
 <<extensions-registration-programmatic-instance-fields, Instance Fields>> for
@@ -196,6 +206,19 @@ extensions to be registered last and _after_ callback extensions to be registere
 relative to other programmatically registered extensions.
 ====
 
+[[extensions-registration-programmatic-inheritance]]
+[NOTE]
+.Extension Inheritance
+====
+Extensions registered via `@RegisterExtension` or `@ExtendWith` on fields in superclasses
+will be inherited.
+
+Furthermore, extensions inherited from superclass fields will be registered before those
+from `@RegisterExtension` and `@ExtendWith` fields in subclasses unless `@Order` is used
+to alter that behavior (see <<extensions-registration-programmatic-order, Extension
+Registration Order>> above).
+====
+
 NOTE: `@RegisterExtension` fields must not be `null` (at evaluation time) but may be
 either `static` or non-static.
 

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

@@ -45,17 +45,15 @@
  *
  * <h2>Inheritance and Execution Order</h2>
  *
- * <p>{@code @AfterAll} methods are inherited from superclasses as long as
- * they are not <em>hidden</em> (default mode with {@code static} modifier),
- * <em>overridden</em>, or <em>superseded</em> (i.e., replaced based on
- * signature only, irrespective of Java's visibility rules). Furthermore,
- * {@code @AfterAll} methods from superclasses will be executed before
- * {@code @AfterAll} methods in subclasses.
+ * <p>{@code @AfterAll} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @AfterAll} methods from superclasses will be
+ * executed after {@code @AfterAll} methods in subclasses.
  *
- * <p>Similarly, {@code @AfterAll} methods declared in an interface are
- * inherited as long as they are not <em>hidden</em> or <em>overridden</em>,
- * and {@code @AfterAll} methods from an interface will be executed after
- * {@code @AfterAll} methods in the class that implements the interface.
+ * <p>Similarly, {@code @AfterAll} methods declared in an interface are inherited
+ * as long as they are not overridden, and {@code @AfterAll} methods from an
+ * interface will be executed after {@code @AfterAll} methods in the class that
+ * implements the interface.
  *
  * <p>JUnit Jupiter does not guarantee the execution order of multiple
  * {@code @AfterAll} methods that are declared within a single test class or

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

@@ -39,10 +39,9 @@
  * <h2>Inheritance and Execution Order</h2>
  *
  * <p>{@code @AfterEach} methods are inherited from superclasses as long as they
- * are not <em>overridden</em> or <em>superseded</em> (i.e., replaced based on
- * signature only, irrespective of Java's visibility rules). Furthermore,
- * {@code @AfterEach} methods from superclasses will be executed after
- * {@code @AfterEach} methods in subclasses.
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @AfterEach} methods from superclasses will be
+ * executed after {@code @AfterEach} methods in subclasses.
  *
  * <p>Similarly, {@code @AfterEach} methods declared as <em>interface default
  * methods</em> are inherited as long as they are not overridden, and

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

@@ -45,17 +45,15 @@
  *
  * <h2>Inheritance and Execution Order</h2>
  *
- * <p>{@code @BeforeAll} methods are inherited from superclasses as long as
- * they are not <em>hidden</em> (default mode with {@code static} modifier),
- * <em>overridden</em>, or <em>superseded</em> (i.e., replaced based on
- * signature only, irrespective of Java's visibility rules). Furthermore,
- * {@code @BeforeAll} methods from superclasses will be executed before
- * {@code @BeforeAll} methods in subclasses.
+ * <p>{@code @BeforeAll} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @BeforeAll} methods from superclasses will be
+ * executed before {@code @BeforeAll} methods in subclasses.
  *
- * <p>Similarly, {@code @BeforeAll} methods declared in an interface are
- * inherited as long as they are not <em>hidden</em> or <em>overridden</em>,
- * and {@code @BeforeAll} methods from an interface will be executed before
- * {@code @BeforeAll} methods in the class that implements the interface.
+ * <p>Similarly, {@code @BeforeAll} methods declared in an interface are inherited
+ * as long as they are not overridden, 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

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

@@ -39,10 +39,9 @@
  * <h2>Inheritance and Execution Order</h2>
  *
  * <p>{@code @BeforeEach} methods are inherited from superclasses as long as they
- * are not <em>overridden</em> or <em>superseded</em> (i.e., replaced based on
- * signature only, irrespective of Java's visibility rules). Furthermore,
- * {@code @BeforeEach} methods from superclasses will be executed before
- * {@code @BeforeEach} methods in subclasses.
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @BeforeEach} methods from superclasses will be
+ * executed before {@code @BeforeEach} methods in subclasses.
  *
  * <p>Similarly, {@code @BeforeEach} methods declared as <em>interface default
  * methods</em> are inherited as long as they are not overridden, and

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

@@ -44,6 +44,13 @@
  * create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @RepeatedTest}.
  *
+ * <h2>Inheritance</h2>
+ *
+ * <p>{@code @RepeatedTest} methods are inherited from superclasses as long as
+ * they are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Similarly, {@code @RepeatedTest} methods declared as <em>interface
+ * default methods</em> are inherited as long as they are not overridden.
+ *
  * <h2>Test Execution Order</h2>
  *
  * <p>By default, test methods will be ordered using an algorithm that is

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

@@ -34,6 +34,13 @@
  * <p>{@code @Test} may also be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of {@code @Test}.
  *
+ * <h2>Inheritance</h2>
+ *
+ * <p>{@code @Test} methods are inherited from superclasses as long as they are
+ * not <em>overridden</em> according to the visibility rules of the Java language.
+ * Similarly, {@code @Test} methods declared as <em>interface default methods</em>
+ * are inherited as long as they are not overridden.
+ *
  * <h2>Test Execution Order</h2>
  *
  * <p>By default, test methods will be ordered using an algorithm that is

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

@@ -43,6 +43,13 @@
  * resolved by {@link org.junit.jupiter.api.extension.ParameterResolver
  * ParameterResolvers}.
  *
+ * <h2>Inheritance</h2>
+ *
+ * <p>{@code @TestFactory} methods are inherited from superclasses as long as
+ * they are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Similarly, {@code @TestFactory} methods declared as <em>interface
+ * default methods</em> are inherited as long as they are not overridden.
+ *
  * <h2>Test Execution Order</h2>
  *
  * <p>By default, test methods will be ordered using an algorithm that is

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

@@ -49,6 +49,13 @@
  * create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @TestTemplate}.
  *
+ * <h2>Inheritance</h2>
+ *
+ * <p>{@code @TestTemplate} methods are inherited from superclasses as long as
+ * they are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Similarly, {@code @TestTemplate} methods declared as <em>interface
+ * default methods</em> are inherited as long as they are not overridden.
+ *
  * <h2>Test Execution Order</h2>
  *
  * <p>By default, test methods will be ordered using an algorithm that is

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtendWith.java

@@ -35,10 +35,10 @@
  *
  * <h2>Inheritance</h2>
  *
- * <p>{@code @ExtendWith} fields are inherited from superclasses as long as they
- * are not <em>hidden</em> or <em>overridden</em>. Furthermore, {@code @ExtendWith}
- * fields from superclasses will be registered before {@code @ExtendWith} fields
- * in subclasses.
+ * <p>{@code @ExtendWith} fields are inherited from superclasses. Furthermore,
+ * {@code @ExtendWith} fields from superclasses will be registered before
+ * {@code @ExtendWith} fields in subclasses unless {@code @Order} is used to
+ * alter that behavior (see below).
  *
  * <h2>Registration Order</h2>
  *

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/RegisterExtension.java

@@ -65,10 +65,10 @@
  *
  * <h2>Inheritance</h2>
  *
- * <p>{@code @RegisterExtension} fields are inherited from superclasses as long
- * as they are not <em>hidden</em> or <em>overridden</em>. Furthermore,
- * {@code @RegisterExtension} fields from superclasses will be registered before
- * {@code @RegisterExtension} fields in subclasses.
+ * <p>{@code @RegisterExtension} fields are inherited from superclasses.
+ * Furthermore, {@code @RegisterExtension} fields from superclasses will be
+ * registered before {@code @RegisterExtension} fields in subclasses unless
+ * {@code @Order} is used to alter that behavior (see below).
  *
  * <h2>Registration Order</h2>
  *

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java

@@ -79,6 +79,14 @@
  * to create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @ParameterizedTest}.
  *
+ * <h2>Inheritance</h2>
+ *
+ * <p>{@code @ParameterizedTest} methods are inherited from superclasses as long
+ * as they are not <em>overridden</em> according to the visibility rules of the
+ * Java language. Similarly, {@code @ParameterizedTest} methods declared as
+ * <em>interface default methods</em> are inherited as long as they are not
+ * overridden.
+ *
  * <h2>Test Execution Order</h2>
  *
  * <p>By default, test methods will be ordered using an algorithm that is