Polish Javadoc and formatting

junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java

@@ -933,21 +933,22 @@ public static String getFullyQualifiedMethodName(Class<?> clazz, Method method)
 	 */
 	public static String getFullyQualifiedMethodName(Class<?> clazz, String methodName, Class<?>... parameterTypes) {
 		Preconditions.notNull(clazz, "Class must not be null");
-		Preconditions.notBlank(methodName, "Method name must not be null or blank");
 
 		return getFullyQualifiedMethodName(clazz.getName(), methodName, ClassUtils.nullSafeToString(parameterTypes));
 	}
 
 	/**
 	 * Build the <em>fully qualified method name</em> for the method described by the
-	 * supplied class, method name, and parameter types.
+	 * supplied class name, method name, and parameter types.
 	 *
 	 * <p>Note that the class is not necessarily the class in which the method is
 	 * declared.
 	 *
-	 * @param className the name of the class from which the method should be referenced; never {@code null}
+	 * @param className the name of the class from which the method should be referenced;
+	 * never {@code null}
 	 * @param methodName the name of the method; never {@code null} or blank
-	 * @param parameterTypeNames the parameter type names of the method; may be empty but not {@code null}
+	 * @param parameterTypeNames the parameter type names of the method; may be
+	 * empty but not {@code null}
 	 * @return fully qualified method name; never {@code null}
 	 * @since 1.11
 	 */

junit-platform-commons/src/main/java/org/junit/platform/commons/util/StringUtils.java

@@ -306,9 +306,10 @@ private static TwoPartSplitResult splitIntoTwo(String value, int index, int leng
 	public interface TwoPartSplitResult {
 
 		/**
-		 * Maps the result of splitting a string into two parts or throw an exception.
+		 * Map the result of splitting a string into two parts or throw an exception.
 		 *
-		 * @param onePartExceptionCreator the exception creator to use if the string was split into a single part
+		 * @param onePartExceptionCreator the exception creator to use if the string
+		 * was split into a single part
 		 * @param twoPartsMapper the mapper to use if the string was split into two parts
 		 */
 		default <T> T mapTwo(Supplier<? extends RuntimeException> onePartExceptionCreator,
@@ -320,7 +321,7 @@ default <T> T mapTwo(Supplier<? extends RuntimeException> onePartExceptionCreato
 		}
 
 		/**
-		 * Maps the result of splitting a string into up to two parts.
+		 * Map the result of splitting a string into up to two parts.
 		 *
 		 * @param onePartMapper the mapper to use if the string was split into a single part
 		 * @param twoPartsMapper the mapper to use if the string was split into two parts
@@ -340,7 +341,7 @@ private static final class OnePart implements TwoPartSplitResult {
 		@Override
 		public <T> T map(Function<String, ? extends T> onePartMapper,
 				BiFunction<String, String, ? extends T> twoPartsMapper) {
-			return onePartMapper.apply(value);
+			return onePartMapper.apply(this.value);
 		}
 	}
 
@@ -357,7 +358,7 @@ private static final class TwoParts implements TwoPartSplitResult {
 		@Override
 		public <T> T map(Function<String, ? extends T> onePartMapper,
 				BiFunction<String, String, ? extends T> twoPartsMapper) {
-			return twoPartsMapper.apply(first, second);
+			return twoPartsMapper.apply(this.first, this.second);
 		}
 	}
 

junit-platform-console/src/main/java/org/junit/platform/console/options/SelectorConverter.java

@@ -93,19 +93,16 @@ public ClasspathResourceSelector convert(String value) {
 	}
 
 	static class Iteration implements ITypeConverter<IterationSelector> {
-
 		@Override
 		public IterationSelector convert(String value) {
 			DiscoverySelectorIdentifier identifier = DiscoverySelectorIdentifier.create(
 				IterationSelector.IdentifierParser.PREFIX, value);
 			return (IterationSelector) DiscoverySelectors.parse(identifier) //
 					.orElseThrow(() -> new PreconditionViolationException("Invalid format: Failed to parse selector"));
 		}
-
 	}
 
 	static class Identifier implements ITypeConverter<DiscoverySelectorIdentifier> {
-
 		@Override
 		public DiscoverySelectorIdentifier convert(String value) {
 			return DiscoverySelectorIdentifier.parse(value);

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

@@ -33,12 +33,16 @@ public interface DiscoverySelector {
 	/**
 	 * Return the {@linkplain DiscoverySelectorIdentifier identifier} of this
 	 * selector.
-	 * <p>
-	 * The returned identifier has to be parsable by a corresponding
+	 *
+	 * <p>The returned identifier must be parsable by a corresponding
 	 * {@link DiscoverySelectorIdentifierParser}.
 	 *
-	 * @return the identifier of this selector or empty if it is not supported;
-	 * never {@code null}
+	 * <p>The default implementation returns {@link Optional#empty()}. Can be
+	 * overridden by concrete implementations.
+	 *
+	 * @return an {@link Optional} containing the identifier of this selector;
+	 * never {@code null} but potentially empty if the selector does not support
+	 * identifiers
 	 * @since 1.11
 	 */
 	@API(status = EXPERIMENTAL, since = "1.11")

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

@@ -20,10 +20,9 @@
 import org.junit.platform.commons.util.StringUtils;
 
 /**
- * Identifier for {@link DiscoverySelector DiscoverySelectors} with a specific
- * prefix.
- * <p>
- * The {@linkplain #toString() string representation} of an identifier is
+ * Identifier for a {@link DiscoverySelector} with a specific prefix.
+ *
+ * <p>The {@linkplain #toString() string representation} of an identifier is
  * intended to be human-readable and is formatted as {@code prefix:value}.
  *
  * @since 1.11
@@ -37,7 +36,7 @@ public final class DiscoverySelectorIdentifier {
 	private final String value;
 
 	/**
-	 * Create a new {@link DiscoverySelectorIdentifier} with the supplied prefix and
+	 * Create a new {@code DiscoverySelectorIdentifier} with the supplied prefix and
 	 * value.
 	 *
 	 * @param prefix the prefix; never {@code null} or blank
@@ -51,8 +50,8 @@ public static DiscoverySelectorIdentifier create(String prefix, String value) {
 	 * Parse the supplied string representation of a
 	 * {@link DiscoverySelectorIdentifier} in the format {@code prefix:value}.
 	 *
-	 * @param string the string representation of a {@link DiscoverySelectorIdentifier}
-	 * @return the parsed {@link DiscoverySelectorIdentifier}
+	 * @param string the string representation of a {@code DiscoverySelectorIdentifier}
+	 * @return the parsed {@code DiscoverySelectorIdentifier}
 	 * @throws PreconditionViolationException if the supplied string does not
 	 * conform to the expected format
 	 */
@@ -74,7 +73,7 @@ private DiscoverySelectorIdentifier(String prefix, String value) {
 	 * @return the prefix; never {@code null} or blank
 	 */
 	public String getPrefix() {
-		return prefix;
+		return this.prefix;
 	}
 
 	/**
@@ -83,7 +82,7 @@ public String getPrefix() {
 	 * @return the value; never {@code null} or blank
 	 */
 	public String getValue() {
-		return value;
+		return this.value;
 	}
 
 	@Override
@@ -95,12 +94,12 @@ public boolean equals(Object o) {
 			return false;
 		}
 		DiscoverySelectorIdentifier that = (DiscoverySelectorIdentifier) o;
-		return Objects.equals(prefix, that.prefix) && Objects.equals(value, that.value);
+		return Objects.equals(this.prefix, that.prefix) && Objects.equals(this.value, that.value);
 	}
 
 	@Override
 	public int hashCode() {
-		return Objects.hash(prefix, value);
+		return Objects.hash(this.prefix, this.value);
 	}
 
 	/**
@@ -109,6 +108,7 @@ public int hashCode() {
 	 */
 	@Override
 	public String toString() {
-		return String.format("%s:%s", prefix, value);
+		return String.format("%s:%s", this.prefix, this.value);
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClassSelector.java

@@ -162,5 +162,7 @@ public String getPrefix() {
 		public Optional<ClassSelector> parse(DiscoverySelectorIdentifier identifier, Context context) {
 			return Optional.of(DiscoverySelectors.selectClass(identifier.getValue()));
 		}
+
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClasspathResourceSelector.java

@@ -142,5 +142,7 @@ public Optional<ClasspathResourceSelector> parse(DiscoverySelectorIdentifier ide
 				} //
 			));
 		}
+
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClasspathRootSelector.java

@@ -117,5 +117,7 @@ public Optional<ClasspathRootSelector> parse(DiscoverySelectorIdentifier identif
 			Path path = Paths.get(URI.create(identifier.getValue()));
 			return getFirstElement(DiscoverySelectors.selectClasspathRoots(singleton(path)));
 		}
+
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DirectorySelector.java

@@ -136,5 +136,7 @@ public String getPrefix() {
 		public Optional<DirectorySelector> parse(DiscoverySelectorIdentifier identifier, Context context) {
 			return Optional.of(DiscoverySelectors.selectDirectory(identifier.getValue()));
 		}
+
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectorIdentifierParser.java

@@ -19,10 +19,9 @@
 import org.junit.platform.engine.DiscoverySelectorIdentifier;
 
 /**
- * Parser for {@link DiscoverySelectorIdentifier DiscoverySelectorIdentifiers}
- * with a specific prefix.
- * <p>
- * Implementations of this interface can be registered using the Java service
+ * Parser for a {@link DiscoverySelectorIdentifier} with a specific prefix.
+ *
+ * <p>Implementations of this interface can be registered using the Java service
  * loader mechanism to extend the set of supported prefixes for
  * {@link DiscoverySelectorIdentifier DiscoverySelectorIdentifiers}.
  *
@@ -33,22 +32,23 @@
 public interface DiscoverySelectorIdentifierParser {
 
 	/**
-	 * Get the prefix that this parser can handle.
+	 * Get the prefix that this parser supports.
 	 *
-	 * @return the prefix that this parser can handle; never {@code null}
+	 * @return the prefix that this parser supports; never {@code null} or blank
 	 */
 	String getPrefix();
 
 	/**
 	 * Parse the supplied {@link DiscoverySelectorIdentifier}.
-	 * <p>
-	 * The JUnit Platform will only invoke this method if the supplied
+	 *
+	 * <p>The JUnit Platform will only invoke this method if the supplied
 	 * {@link DiscoverySelectorIdentifier} has a prefix that matches the value
 	 * returned by {@link #getPrefix()}.
 	 *
 	 * @param identifier the {@link DiscoverySelectorIdentifier} to parse
 	 * @param context the {@link Context} to use for parsing
-	 * @return an {@link Optional} containing the parsed {@link DiscoverySelector}; never {@code null}
+	 * @return an {@link Optional} containing the parsed {@link DiscoverySelector};
+	 * never {@code null} but potentially empty
 	 */
 	Optional<? extends DiscoverySelector> parse(DiscoverySelectorIdentifier identifier, Context context);
 
@@ -59,8 +59,8 @@ interface Context {
 
 		/**
 		 * Parse the supplied selector.
-		 * <p>
-		 * This method is intended to be used by implementations of
+		 *
+		 * <p>This method is intended to be used by implementations of
 		 * {@link DiscoverySelectorIdentifierParser#parse} for selectors that
 		 * contain other selectors.
 		 */

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectorIdentifierParsers.java

@@ -75,11 +75,13 @@ private enum Singleton {
 			for (DiscoverySelectorIdentifierParser parser : loadedParsers) {
 				DiscoverySelectorIdentifierParser previous = parsersByPrefix.put(parser.getPrefix(), parser);
 				Preconditions.condition(previous == null,
-					() -> String.format("Duplicate parser for prefix: [%s] candidate a: [%s] candidate b: [%s] ",
+					() -> String.format("Duplicate parser for prefix: [%s]; candidate a: [%s]; candidate b: [%s]",
 						parser.getPrefix(), requireNonNull(previous).getClass().getName(),
 						parser.getClass().getName()));
 			}
 			this.parsersByPrefix = unmodifiableMap(parsersByPrefix);
 		}
+
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java

@@ -930,8 +930,8 @@ public static UniqueIdSelector selectUniqueId(String uniqueId) {
 	 *
 	 * @param parentSelector the parent selector to select iterations for; never
 	 * {@code null}
-	 * @param iterationIndices the iteration indices to select; never
-	 * {@code null} or empty
+	 * @param iterationIndices the iteration indices to select; never {@code null}
+	 * or empty
 	 * @since 1.9
 	 * @see IterationSelector
 	 */
@@ -943,11 +943,12 @@ public static IterationSelector selectIteration(DiscoverySelector parentSelector
 	}
 
 	/**
-	 * Parse the supplied string representation of a
-	 * {@link DiscoverySelectorIdentifier}.
+	 * Parse the supplied string representation of a {@link DiscoverySelectorIdentifier}.
 	 *
 	 * @param identifier the string representation of a {@code DiscoverySelectorIdentifier};
 	 * never {@code null} or blank
+	 * @return an {@link Optional} containing the corresponding {@link DiscoverySelector};
+	 * never {@code null} but potentially empty
 	 * @since 1.11
 	 * @see DiscoverySelectorIdentifierParser
 	 */
@@ -961,6 +962,8 @@ public static Optional<? extends DiscoverySelector> parse(String identifier) {
 	 *
 	 * @param identifier the {@code DiscoverySelectorIdentifier} to parse;
 	 * never {@code null}
+	 * @return an {@link Optional} containing the corresponding {@link DiscoverySelector};
+	 * never {@code null} but potentially empty
 	 * @since 1.11
 	 * @see DiscoverySelectorIdentifierParser
 	 */
@@ -975,6 +978,8 @@ public static Optional<? extends DiscoverySelector> parse(DiscoverySelectorIdent
 	 *
 	 * @param identifiers the string representations of
 	 * {@code DiscoverySelectorIdentifiers} to parse; never {@code null}
+	 * @return a stream of the corresponding {@link DiscoverySelector DiscoverySelectors};
+	 * never {@code null} but potentially empty
 	 * @since 1.11
 	 * @see DiscoverySelectorIdentifierParser
 	 */
@@ -989,11 +994,14 @@ public static Stream<? extends DiscoverySelector> parseAll(String... identifiers
 	 *
 	 * @param identifiers the {@code DiscoverySelectorIdentifiers} to parse;
 	 * never {@code null}
+	 * @return a stream of the corresponding {@link DiscoverySelector DiscoverySelectors};
+	 * never {@code null} but potentially empty
 	 * @since 1.11
 	 * @see DiscoverySelectorIdentifierParser
 	 */
 	@API(status = EXPERIMENTAL, since = "1.11")
 	public static Stream<? extends DiscoverySelector> parseAll(Collection<DiscoverySelectorIdentifier> identifiers) {
 		return DiscoverySelectorIdentifierParsers.parseAll(identifiers);
 	}
+
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/FileSelector.java

@@ -112,7 +112,7 @@ public boolean equals(Object o) {
 	@API(status = STABLE, since = "1.3")
 	@Override
 	public int hashCode() {
-		return Objects.hash(path, position);
+		return Objects.hash(this.path, this.position);
 	}
 
 	@Override
@@ -158,5 +158,7 @@ public Optional<FileSelector> parse(DiscoverySelectorIdentifier identifier, Cont
 				} //
 			));
 		}
+
 	}
+
 }