Document test and container are non-exclusive properties

* Define test and container as non-exclusive properties.
* Use emphasis to distinguish between term and word.
* Document that TestDescriptor.Type values are exclusive properties.
* Document that `getChildren()`, `getDescendants()` and
  `mayRegisterTests()` must be consistent with `isContainer()`.

Author: mpkorstanje

junit-platform-engine/src/main/java/org/junit/platform/engine/TestDescriptor.java

@@ -27,8 +27,8 @@
 import org.junit.platform.commons.util.Preconditions;
 
 /**
- * Mutable descriptor for a test or container that has been discovered by a
- * {@link TestEngine}.
+ * Mutable descriptor for a test or container that has
+ * been discovered by a {@link TestEngine}.
  *
  * @since 1.0
  * @see TestEngine
@@ -106,6 +106,9 @@ default String getLegacyReportingName() {
 	/**
 	 * Get the immutable set of <em>children</em> of this descriptor.
 	 *
+	 * <p>The implementation must be consistent with {@link #isContainer()} such that
+	 * {@code !x.container()} implies {@code x.getChildren().isEmpty()}.
+	 *
 	 * @return the set of children of this descriptor; neither {@code null}
 	 * nor mutable, but potentially empty
 	 * @see #getDescendants()
@@ -141,6 +144,9 @@ default Set<? extends TestDescriptor> getAncestors() {
 	 * <p>A <em>descendant</em> is a child of this descriptor or a child of one of
 	 * its children, recursively.
 	 *
+	 * <p>The implementation must be consistent with {@link #isContainer()} such that
+	 * {@code !x.container()} implies {@code x.getDescendants().isEmpty()}.
+	 *
 	 * @see #getChildren()
 	 */
 	default Set<? extends TestDescriptor> getDescendants() {
@@ -230,7 +236,11 @@ default boolean isRoot() {
 	Type getType();
 
 	/**
-	 * Determine if this descriptor describes a container.
+	 * Determine if this descriptor describes a <em>container</em>.
+	 *
+	 * <p>A test descriptor is a <em>container</em> when it may contain other
+	 * containers or tests as its children. A <em>container</em> can also be a
+	 * <em>test</em>.
 	 *
 	 * <p>The default implementation delegates to {@link Type#isContainer()}.
 	 */
@@ -239,7 +249,11 @@ default boolean isContainer() {
 	}
 
 	/**
-	 * Determine if this descriptor describes a test.
+	 * Determine if this descriptor describes a <em>test</em>.
+	 *
+	 * <p>A test descriptor is a <em>test</em> when it verifies expected
+	 * behavior when executed. A <em>test</em> can also be a
+	 * <em>container</em>.
 	 *
 	 * <p>The default implementation delegates to {@link Type#isTest()}.
 	 */
@@ -250,6 +264,9 @@ default boolean isTest() {
 	/**
 	 * Determine if this descriptor may register dynamic tests during execution.
 	 *
+	 * <p>The implementation must be consistent with {@link #isContainer()} such that
+	 * {@code !x.container()} implies {@code !x.mayRegisterTests()}.
+	 * 
 	 * <p>The default implementation assumes tests are usually known during
 	 * discovery and thus returns {@code false}.
 	 */
@@ -259,7 +276,7 @@ default boolean mayRegisterTests() {
 
 	/**
 	 * Determine if the supplied descriptor (or any of its descendants)
-	 * {@linkplain TestDescriptor#isTest() is a test} or
+	 * {@linkplain TestDescriptor#isTest() is a <em>test</em>} or
 	 * {@linkplain TestDescriptor#mayRegisterTests() may potentially register
 	 * tests dynamically}.
 	 *
@@ -355,12 +372,14 @@ static Visitor composite(Visitor... visitors) {
 	enum Type {
 
 		/**
-		 * Denotes that the {@link TestDescriptor} is for a <em>container</em>.
+		 * Denotes that the {@link TestDescriptor} is strictly for a
+		 * <em>container</em>. I.e. it is not also a <em>test</em>.
 		 */
 		CONTAINER,
 
 		/**
-		 * Denotes that the {@link TestDescriptor} is for a <em>test</em>.
+		 * Denotes that the {@link TestDescriptor} is strictly for a
+		 * <em>test</em>. I.e. it is not also a <em>container</em>.
 		 */
 		TEST,