Document display names and defaults across the project

Issue: #153

documentation/src/docs/asciidoc/writing-tests.adoc

@@ -166,8 +166,9 @@ There are currently two built-in resolvers that are registered automatically.
 * `{TestInfoParameterResolver}`: if a method parameter is of type `{TestInfo}`, the
   `TestInfoParameterResolver` will supply an instance of `TestInfo` corresponding to the
   current test as the value for the parameter. The `TestInfo` can then be used to retrieve
-  information about the current test such as the test's name, display name (as
-  configured via `@DisplayName`) or associated tags.
+  information about the current test such as the test's display name, the test class, the
+  test method, or associated tags. The display name is either a technical name, such as
+  the name of the test class or test method, or a custom name configured via `@DisplayName`.
 +
 `{TestInfo}` acts as a drop-in replacement for the `TestName`
 rule from JUnit 4. Here is an example of its usage:

junit-engine-api/src/main/java/org/junit/gen5/engine/TestDescriptor.java

@@ -37,11 +37,15 @@ public interface TestDescriptor {
 	/**
 	 * Get the display name of the represented test or container.
 	 *
-	 * <p>The <em>display name</em> is a human-readable name for a test or
-	 * container. It must not be parsed or processed besides being displayed
-	 * to end-users.
+	 * <p>A <em>display name</em> is a human-readable name for a test or
+	 * container that is typically used for test reporting in IDEs and build
+	 * tools. Display names may contain spaces, special characters, and emoji,
+	 * and the format may be customized by {@link TestEngine TestEngines} or
+	 * potentially by end users as well. Consequently, display names should
+	 * never be parsed; rather, they should be used for display purposes only.
 	 *
 	 * @return the display name for this descriptor; never {@code null} or empty
+	 * @see #getSource()
 	 */
 	String getDisplayName();
 

junit-launcher/src/main/java/org/junit/gen5/launcher/TestIdentifier.java

@@ -100,11 +100,17 @@ public Optional<String> getParentId() {
 	/**
 	 * Get the display name of the represented test or container.
 	 *
-	 * <p>The <em>display name</em> is a human-readable name for a test or
-	 * container. It must not be parsed or processed besides being displayed
-	 * to end-users.
+	 * <p>A <em>display name</em> is a human-readable name for a test or
+	 * container that is typically used for test reporting in IDEs and build
+	 * tools. Display names may contain spaces, special characters, and emoji,
+	 * and the format may be customized by {@link org.junit.gen5.engine.TestEngine
+	 * TestEngines} or potentially by end users as well. Consequently, display
+	 * names should never be parsed; rather, they should be used for display
+	 * purposes only.
 	 *
 	 * @return the display name for this identifier; never {@code null} or empty
+	 * @see #getSource()
+	 * @see org.junit.gen5.engine.TestDescriptor#getDisplayName()
 	 */
 	public String getDisplayName() {
 		return this.displayName;

junit5-api/src/main/java/org/junit/gen5/api/TestInfo.java

@@ -19,8 +19,8 @@
 import org.junit.gen5.commons.meta.API;
 
 /**
- * {@code TestInfo} is used to inject information about the current test
- * into to {@code @Test}, {@code @BeforeEach}, {@code @AfterEach},
+ * {@code TestInfo} is used to inject information about the current test or
+ * container into to {@code @Test}, {@code @BeforeEach}, {@code @AfterEach},
  * {@code @BeforeAll}, and {@code @AfterAll} methods.
  *
  * <p>If a method parameter is of type {@link TestInfo}, JUnit will supply
@@ -35,23 +35,44 @@
 public interface TestInfo {
 
 	/**
-	 * Get the display name of the current test.
+	 * Get the display name of the current test or container.
 	 *
-	 * <p>The display name is either the canonical name of the test or a
-	 * custom name configured via {@link DisplayName @DisplayName}.
+	 * <p>The display name is either a default name or a custom name configured
+	 * via {@link DisplayName @DisplayName}.
 	 *
-	 * @return the display name of the test; never {@code null}
+	 * <h3>Default Display Names</h3>
+	 *
+	 * <p>If the context in which {@code TestInfo} is used is at the container
+	 * level, the default display name is the fully qualified class name for the
+	 * test class. If the context in which {@code TestInfo} is used is at the
+	 * test level, the default display name is the name of the test method
+	 * concatenated with a comma-separated list of parameter types in parentheses.
+	 * The names of parameter types are retrieved using {@link Class#getSimpleName()}.
+	 * For example, the default display name for the following test method is
+	 * {@code testUser(TestInfo, User)}.
+	 *
+	 * <pre style="code">
+	 *   {@literal @}Test
+	 *   void testUser(TestInfo testInfo, {@literal @}Mock User user) { ... }
+	 * </pre>
+	 *
+	 * <p>Note that display names are typically used for test reporting in IDEs
+	 * and build tools and may contain spaces, special characters, and even emoji.
+	 *
+	 * @return the display name of the test or container; never {@code null} or empty
 	 */
 	String getDisplayName();
 
 	/**
-	 * Get the set of all tags. Might be declared directly on this element
-	 * or "inherited" from an outer context.
+	 * Get the set of all tags for the current test or container.
+	 *
+	 * <p>Tags may be declared directly on the test element or <em>inherited</em>
+	 * from an outer context.
 	 */
 	Set<String> getTags();
 
 	/**
-	 * Get the {@link Class} associated with the current test, if available.
+	 * Get the {@link Class} associated with the current test or container, if available.
 	 */
 	Optional<Class<?>> getTestClass();
 

junit5-api/src/main/java/org/junit/gen5/api/extension/ExtensionContext.java

@@ -49,8 +49,28 @@ public interface ExtensionContext {
 	/**
 	 * Get the display name for the current test or container.
 	 *
-	 * <p>Display names should only be used for test reporting in IDEs and
-	 * build tools and may contain spaces, special characters, and even emoji.
+	 * <p>The display name is either a default name or a custom name configured
+	 * via {@link org.junit.gen5.api.DisplayName @DisplayName}.
+	 *
+	 * <h3>Default Display Names</h3>
+	 *
+	 * <p>If this context represents a container, the default display name is
+	 * the fully qualified class name for the container class. If this context
+	 * represents a test, the default display name is the name of the test method
+	 * concatenated with a comma-separated list of parameter types in parentheses.
+	 * The names of parameter types are retrieved using {@link Class#getSimpleName()}.
+	 * For example, the default display name for the following test method is
+	 * {@code testUser(TestInfo, User)}.
+	 *
+	 * <pre style="code">
+	 *   {@literal @}Test
+	 *   void testUser(TestInfo testInfo, {@literal @}Mock User user) { ... }
+	 * </pre>
+	 *
+	 * <p>Note that display names are typically used for test reporting in IDEs
+	 * and build tools and may contain spaces, special characters, and even emoji.
+	 *
+	 * @return the display name of the test or container; never {@code null} or empty
 	 */
 	String getDisplayName();
 

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/descriptor/ClassTestDescriptor.java

@@ -51,6 +51,11 @@
 /**
  * {@link TestDescriptor} for tests based on Java classes.
  *
+ * <h3>Default Display Names</h3>
+ *
+ * <p>The default display name for a test class is the fully qualified name of
+ * the class.
+ *
  * @since 5.0
  */
 @API(Internal)

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/descriptor/MethodTestDescriptor.java

@@ -46,6 +46,19 @@
 /**
  * {@link TestDescriptor} for tests based on Java methods.
  *
+ * <h3>Default Display Names</h3>
+ *
+ * <p>The default display name for a test method is the name of the method
+ * concatenated with a comma-separated list of parameter types in parentheses.
+ * The names of parameter types are retrieved using {@link Class#getSimpleName()}.
+ * For example, the default display name for the following test method is
+ * {@code testUser(TestInfo, User)}.
+ *
+ * <pre style="code">
+ *   {@literal @}Test
+ *   void testUser(TestInfo testInfo, {@literal @}Mock User user) { ... }
+ * </pre>
+ *
  * @since 5.0
  */
 @API(Internal)