Polish Javadoc and Filter implementations

Issue: #234

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

@@ -15,16 +15,16 @@
 import org.junit.gen5.commons.meta.API;
 
 /**
- * Filters particular tests during test discovery.
+ * A {@link DiscoveryFilter} is applied during test discovery to determine if
+ * a given container or test should be included in the test plan.
  *
- * <p>These filters need to be applied by the {@link TestEngine} during test
- * discovery.
+ * <p>{@link TestEngine TestEngines} should apply {@code DiscoveryFilters}
+ * during the test discovery phase.
  *
  * @since 5.0
  * @see EngineDiscoveryRequest
  * @see TestEngine
  */
 @API(Experimental)
 public interface DiscoveryFilter<T> extends Filter<T> {
-
 }

junit-engine-api/src/main/java/org/junit/gen5/engine/discovery/ClassFilter.java

@@ -16,11 +16,24 @@
 import org.junit.gen5.engine.DiscoveryFilter;
 
 /**
+ * {@link DiscoveryFilter} that is applied to a {@link Class}.
+ *
  * @since 5.0
+ * @see #byNamePattern(String)
  */
 @API(Experimental)
 public interface ClassFilter extends DiscoveryFilter<Class<?>> {
 
+	/**
+	 * Create a {@link ClassFilter} based on the supplied class name pattern.
+	 *
+	 * <p>If the fully qualified name of a class matches against the pattern,
+	 * the class will be included in the result set.
+	 *
+	 * @param pattern a regular expression to match against fully qualified
+	 * class names; never {@code null} or empty
+	 * @see Class#getName()
+	 */
 	static ClassFilter byNamePattern(String pattern) {
 		return new ClassNameFilter(pattern);
 	}

junit-engine-api/src/main/java/org/junit/gen5/engine/discovery/ClassNameFilter.java

@@ -14,24 +14,30 @@
 
 import java.util.regex.Pattern;
 
+import org.junit.gen5.commons.util.Preconditions;
 import org.junit.gen5.engine.FilterResult;
 
 /**
+ * {@link ClassFilter} that matches fully qualified class names against a
+ * pattern in the form of a regular expression.
+ *
  * @since 5.0
  */
 class ClassNameFilter implements ClassFilter {
 
 	private final Pattern pattern;
 
 	ClassNameFilter(String pattern) {
+		Preconditions.notBlank(pattern, "pattern must not be null or empty");
 		this.pattern = Pattern.compile(pattern);
 	}
 
 	@Override
-	public FilterResult apply(Class<?> testClass) {
-		return includedIf(pattern.matcher(testClass.getName()).matches(), //
-			() -> "Test class matches name pattern: " + pattern, //
-			() -> "Test class does not match name pattern: " + pattern);
+	public FilterResult apply(Class<?> clazz) {
+		String name = clazz.getName();
+		return includedIf(pattern.matcher(name).matches(), //
+			() -> String.format("Class name [%s] matches pattern: %s", name, pattern), //
+			() -> String.format("Class name [%s] does not match pattern: %s", name, pattern));
 	}
 
 	@Override

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

@@ -21,8 +21,8 @@
  * A {@code PostDiscoveryFilter} is applied to {@link TestDescriptor TestDescriptors}
  * after test discovery.
  *
- * <p>A {@code PostDiscoveryFilter} must not be applied by a {@link TestEngine}
- * during test discovery.
+ * <p>{@link TestEngine TestEngines} must <strong>not</strong> apply
+ * {@code PostDiscoveryFilters} during the test discovery phase.
  *
  * @since 5.0
  * @see TestDiscoveryRequest