Document TestDiscoveryRequest and TestDiscoveryRequestBuilder (#234)

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

@@ -34,26 +34,59 @@
 @API(Experimental)
 public interface TestDiscoveryRequest extends EngineDiscoveryRequest {
 
+	/**
+	 * Adds the supplied {@code selector} to this request.
+	 */
 	void addSelector(DiscoverySelector selector);
 
+	/**
+	 * Adds all of the supplied {@code selectors} to this request.
+	 */
 	void addSelectors(Collection<DiscoverySelector> selectors);
 
+	/**
+	 * Adds the supplied {@code engineIdFilter} to this request.
+	 */
 	void addEngineIdFilter(EngineIdFilter engineIdFilter);
 
+	/**
+	 * Adds all of the supplied {@code engineIdFilters} to this request.
+	 */
 	void addEngineIdFilters(Collection<EngineIdFilter> engineIdFilters);
 
+	/**
+	 * Adds the supplied {@code discoveryFilter} to this request.
+	 */
 	void addFilter(DiscoveryFilter<?> discoveryFilter);
 
+	/**
+	 * Adds all of the supplied {@code discoveryFilters} to this request.
+	 */
 	void addFilters(Collection<DiscoveryFilter<?>> discoveryFilters);
 
+	/**
+	 * Adds the supplied {@code postDiscoveryFilter} to this request.
+	 */
 	void addPostFilter(PostDiscoveryFilter postDiscoveryFilter);
 
+	/**
+	 * Adds all of the supplied {@code postDiscoveryFilters} to this request.
+	 */
 	void addPostFilters(Collection<PostDiscoveryFilter> postDiscoveryFilters);
 
+	/**
+	 * Adds the supplied {@code configurationParameters} to this request.
+	 */
 	void addConfigurationParameters(Map<String, String> configurationParameters);
 
+	/**
+	 * Returns the {@code engineIdFilters} that have been added to this request.
+	 */
 	List<EngineIdFilter> getEngineIdFilters();
 
+	/**
+	 * Returns the {@code postDiscoveryFilters} that have been added to this request.
+	 */
 	List<PostDiscoveryFilter> getPostDiscoveryFilters();
 
 }

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

@@ -70,37 +70,55 @@ public final class TestDiscoveryRequestBuilder {
 	private List<PostDiscoveryFilter> postDiscoveryFilters = new LinkedList<>();
 	private Map<String, String> configurationParameters = new HashMap<>();
 
+	/**
+	 * Returns a new {@link TestDiscoveryRequestBuilder}.
+	 */
 	public static TestDiscoveryRequestBuilder request() {
 		return new TestDiscoveryRequestBuilder();
 	}
 
-	public TestDiscoveryRequestBuilder select(DiscoverySelector... elements) {
-		if (elements != null) {
-			select(Arrays.asList(elements));
+	/**
+	 * Adds all of the supplied {@code selectors} to the request.
+	 */
+	public TestDiscoveryRequestBuilder select(DiscoverySelector... selectors) {
+		if (selectors != null) {
+			select(Arrays.asList(selectors));
 		}
 		return this;
 	}
 
-	public TestDiscoveryRequestBuilder select(List<DiscoverySelector> elements) {
-		if (elements != null) {
-			this.selectors.addAll(elements);
+	/**
+	 * Adds all of the supplied {@code selectors} to the request.
+	 */
+	public TestDiscoveryRequestBuilder select(List<DiscoverySelector> selectors) {
+		if (selectors != null) {
+			this.selectors.addAll(selectors);
 		}
 		return this;
 	}
 
+	/**
+	 * Adds all of the supplied {@code filters} to the request.
+	 */
 	public TestDiscoveryRequestBuilder filter(Filter<?>... filters) {
 		if (filters != null) {
 			Arrays.stream(filters).forEach(this::storeFilter);
 		}
 		return this;
 	}
 
+	/**
+	 * Adds the supplied <em>configuration parameter</em> to the request.
+	 */
 	public TestDiscoveryRequestBuilder configurationParameter(String key, String value) {
 		Preconditions.notBlank(key, "configuration parameter key must not be null or empty");
 		this.configurationParameters.put(key, value);
 		return this;
 	}
 
+	/**
+	 * Adds all of the supplied {@code configurationParameters} to the request.
+	 */
 	public TestDiscoveryRequestBuilder configurationParameters(Map<String, String> configurationParameters) {
 		if (configurationParameters != null) {
 			configurationParameters.forEach(this::configurationParameter);
@@ -125,6 +143,10 @@ else if (filter instanceof DiscoveryFilter<?>) {
 		}
 	}
 
+	/**
+	 * Builds and returns the {@link TestDiscoveryRequest} that has previously
+	 * been setup by the methods of this builder.
+	 */
 	public TestDiscoveryRequest build() {
 		DiscoveryRequest discoveryRequest = new DiscoveryRequest();
 		discoveryRequest.addSelectors(this.selectors);