Overhaul Javadoc for Discovery Requests

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

@@ -17,27 +17,29 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * Provides {@link TestEngine TestEngines} access to the information necessary
- * to discover {@link TestDescriptor TestDescriptors}.
+ * {@code EngineDiscoveryRequest} provides a {@link TestEngine} access to the
+ * information necessary to discover tests and containers.
  *
  * <p>A request is comprised of {@linkplain DiscoverySelector selectors} and
- * {@linkplain DiscoveryFilter filters}. While the former specify which tests
- * are to be <em>selected</em>, the latter specify how they are to be
- * <em>filtered</em>.
+ * {@linkplain DiscoveryFilter filters}. While the former <em>select</em>
+ * resources that engines can use to discover tests, the latter specify how
+ * such resources are to be <em>filtered</em>.
  *
  * <p>In addition, the supplied {@linkplain ConfigurationParameters
- * configuration parameters} may be used to influence the discovery process.
+ * configuration parameters} can be used to influence the discovery process.
  *
  * @see TestEngine
+ * @see TestDescriptor
  * @see DiscoverySelector
  * @see DiscoveryFilter
+ * @see ConfigurationParameters
  * @since 1.0
  */
 @API(Experimental)
 public interface EngineDiscoveryRequest {
 
 	/**
-	 * Get the {@link DiscoverySelector DiscoverySelectors} of this request,
+	 * Get the {@link DiscoverySelector DiscoverySelectors} for this request,
 	 * filtered by a particular type.
 	 *
 	 * @param selectorType the type of {@link DiscoverySelector} to filter by
@@ -46,7 +48,7 @@ public interface EngineDiscoveryRequest {
 	<T extends DiscoverySelector> List<T> getSelectorsByType(Class<T> selectorType);
 
 	/**
-	 * Get the {@link DiscoveryFilter DiscoveryFilters} of this request, filtered
+	 * Get the {@link DiscoveryFilter DiscoveryFilters} for this request, filtered
 	 * by a particular type.
 	 *
 	 * @param filterType the type of {@link DiscoveryFilter} to filter by
@@ -55,7 +57,7 @@ public interface EngineDiscoveryRequest {
 	<T extends DiscoveryFilter<?>> List<T> getDiscoveryFiltersByType(Class<T> filterType);
 
 	/**
-	 * Get the {@link ConfigurationParameters} of this request.
+	 * Get the {@link ConfigurationParameters} for this request.
 	 */
 	ConfigurationParameters getConfigurationParameters();
 

junit-platform-launcher/src/main/java/org/junit/platform/launcher/TestDiscoveryRequest.java

@@ -15,30 +15,57 @@
 import java.util.List;
 
 import org.junit.platform.commons.meta.API;
+import org.junit.platform.engine.ConfigurationParameters;
+import org.junit.platform.engine.DiscoveryFilter;
+import org.junit.platform.engine.DiscoverySelector;
 import org.junit.platform.engine.EngineDiscoveryRequest;
 
 /**
- * {@code TestDiscoveryRequest} is an extension of {@link EngineDiscoveryRequest}
- * that provides access to filters which are applied by the {@link Launcher} itself.
+ * {@code TestDiscoveryRequest} extends the {@link EngineDiscoveryRequest} API
+ * with additional filters that are applied by the {@link Launcher} itself.
+ *
+ * <p>Specifically, a {@code TestDiscoveryRequest} contains the following.
+ *
+ * <ul>
+ * <li>{@linkplain EngineFilter Engine Filters}: filters that are applied before
+ * each {@code TestEngine} is executed</li>
+ * <li>{@linkplain ConfigurationParameters Configuration Parameters}: configuration
+ * parameters that can be used to influence the discovery process</li>
+ * <li>{@linkplain DiscoverySelector Discovery Selectors}: components that select
+ * resources that a {@code TestEngine} can use to discover tests</li>
+ * <li>{@linkplain DiscoveryFilter Discovery Filters}: filters that should be applied
+ * by {@code TestEngines} during test discovery</li>
+ * <li>{@linkplain PostDiscoveryFilter Post-Discovery Filters}: filters that will be
+ * applied by the {@code Launcher} after {@code TestEngines} have performed test
+ * discovery</li>
+ * </ul>
  *
  * @since 1.0
+ * @see EngineDiscoveryRequest
+ * @see EngineFilter
+ * @see ConfigurationParameters
+ * @see DiscoverySelector
+ * @see DiscoveryFilter
+ * @see PostDiscoveryFilter
+ * @see #getEngineFilters()
+ * @see #getPostDiscoveryFilters()
  */
 @API(Experimental)
 public interface TestDiscoveryRequest extends EngineDiscoveryRequest {
 
 	/**
-	 * Get the {@code EngineFilters} that have been added to this request.
+	 * Get the {@code EngineFilters} for this request.
 	 *
-	 * @return the list of {@code EngineFilters} that have been added to this
-	 * request; never {@code null} but potentially empty
+	 * @return the list of {@code EngineFilters} for this request; never
+	 * {@code null} but potentially empty
 	 */
 	List<EngineFilter> getEngineFilters();
 
 	/**
-	 * Get the {@code PostDiscoveryFilters} that have been added to this request.
+	 * Get the {@code PostDiscoveryFilters} for this request.
 	 *
-	 * @return the list of {@code PostDiscoveryFilters} that have been added to
-	 * this request; never {@code null} but potentially empty
+	 * @return the list of {@code PostDiscoveryFilters} for this request; never
+	 * {@code null} but potentially empty
 	 */
 	List<PostDiscoveryFilter> getPostDiscoveryFilters();
 

junit-platform-launcher/src/main/java/org/junit/platform/launcher/core/DiscoveryRequest.java → junit-platform-launcher/src/main/java/org/junit/platform/launcher/core/DefaultDiscoveryRequest.java

@@ -19,36 +19,18 @@
 import org.junit.platform.engine.ConfigurationParameters;
 import org.junit.platform.engine.DiscoveryFilter;
 import org.junit.platform.engine.DiscoverySelector;
-import org.junit.platform.engine.TestEngine;
+import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.launcher.EngineFilter;
 import org.junit.platform.launcher.PostDiscoveryFilter;
 import org.junit.platform.launcher.TestDiscoveryRequest;
 
 /**
- * {@code DiscoveryRequest} represents the configuration for test
- * discovery and execution. It is passed to every active {@link TestEngine}
- * and should be used to look up tests for the given configuration.
- *
- * <p>A {@code DiscoveryRequest} contains different configuration options.
- *
- * <ul>
- * <li>{@link DiscoverySelector}: a selector defines where a {@code TestEngine}
- * should look up tests</li>
- * <li>{@link EngineFilter}: a filter that is applied before each
- * {@code TestEngine} is executed</li>
- * <li>{@link DiscoveryFilter}: a filter that should be applied by
- * {@code TestEngines} during test discovery</li>
- * <li>{@link PostDiscoveryFilter}: a filter that will be applied by the
- * launcher after {@code TestEngines} have performed test discovery</li>
- * </ul>
+ * {@code DefaultDiscoveryRequest} is the default implementation of the
+ * {@link EngineDiscoveryRequest} and {@link TestDiscoveryRequest} APIs.
  *
  * @since 1.0
- * @see DiscoverySelector
- * @see EngineFilter
- * @see DiscoveryFilter
- * @see PostDiscoveryFilter
  */
-final class DiscoveryRequest implements TestDiscoveryRequest {
+final class DefaultDiscoveryRequest implements TestDiscoveryRequest {
 
 	// Selectors provided to the engines to be used for discovering tests
 	private final List<DiscoverySelector> selectors;
@@ -65,7 +47,7 @@ final class DiscoveryRequest implements TestDiscoveryRequest {
 	// Configuration parameters can be used to provide custom configuration to engines, e.g. for extensions
 	private final LauncherConfigurationParameters configurationParameters;
 
-	DiscoveryRequest(List<DiscoverySelector> selectors, List<EngineFilter> engineFilters,
+	DefaultDiscoveryRequest(List<DiscoverySelector> selectors, List<EngineFilter> engineFilters,
 			List<DiscoveryFilter<?>> discoveryFilters, List<PostDiscoveryFilter> postDiscoveryFilters,
 			LauncherConfigurationParameters configurationParameters) {
 		this.selectors = selectors;

junit-platform-launcher/src/main/java/org/junit/platform/launcher/core/TestDiscoveryRequestBuilder.java

@@ -170,7 +170,7 @@ else if (filter instanceof DiscoveryFilter<?>) {
 	public TestDiscoveryRequest build() {
 		LauncherConfigurationParameters launcherConfigurationParameters = new LauncherConfigurationParameters(
 			this.configurationParameters);
-		return new DiscoveryRequest(this.selectors, this.engineFilters, this.discoveryFilters,
+		return new DefaultDiscoveryRequest(this.selectors, this.engineFilters, this.discoveryFilters,
 			this.postDiscoveryFilters, launcherConfigurationParameters);
 	}
 

platform-tests/src/test/java/org/junit/platform/launcher/core/DiscoveryRequestTests.java

@@ -26,7 +26,7 @@
 import org.junit.platform.engine.discovery.UniqueIdSelector;
 
 /**
- * Unit tests for {@link DiscoveryRequest}.
+ * Unit tests for {@link DefaultDiscoveryRequest}.
  *
  * @since 1.0
  */

platform-tests/src/test/java/org/junit/platform/launcher/core/TestDiscoveryRequestBuilderTests.java

@@ -112,7 +112,7 @@ public void methodsByClassAreStoredInDiscoveryRequest() throws Exception {
 			Method testMethod = testClass.getMethod("test");
 
 			// @formatter:off
-			DiscoveryRequest discoveryRequest = (DiscoveryRequest) request()
+			DefaultDiscoveryRequest discoveryRequest = (DefaultDiscoveryRequest) request()
 					.selectors(
 							selectMethod(SampleTestClass.class, "test")
 					).build();