Document TestSource interfaces and implementations (#234)

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

@@ -17,6 +17,16 @@
 import org.junit.gen5.commons.meta.API;
 
 /**
+ * Representation of the source of a test or container used to navigate to
+ * its location by IDEs and build tools.
+ *
+ * <p>This is a marker interface. Clients need to check instances for concrete
+ * subclasses or subinterfaces.
+ *
+ * <p>Implementations of this interface need to ensure that they are
+ * <em>serializable</em> and <em>immutable</em> since they may be used as data
+ * transfer objects.
+ *
  * @since 5.0
  */
 @API(Experimental)

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/DirectorySource.java

@@ -22,6 +22,8 @@
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * Directory based {@link org.junit.gen5.engine.TestSource}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -31,6 +33,12 @@ public class DirectorySource implements FileSystemSource {
 
 	private final File directory;
 
+	/**
+	 * Create a new {@code DirectorySource} using the supplied
+	 * {@linkplain File directory}.
+	 *
+	 * @param directory the source directory; must not be null
+	 */
 	public DirectorySource(File directory) {
 		Preconditions.notNull(directory, "directory must not be null");
 		try {

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/FilePosition.java

@@ -19,6 +19,9 @@
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * Position inside a file represented by {@linkplain #getLine line} and
+ * {@linkplain #getColumn column}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -29,15 +32,28 @@ public class FilePosition implements Serializable {
 	private final int line;
 	private final int column;
 
+	/**
+	 * Create a new {@code FilePosition} using the supplied {@code line} and
+	 * {@code column}.
+	 *
+	 * @param line the line (1-based)
+	 * @param column the column (1-based)
+	 */
 	public FilePosition(int line, int column) {
 		this.line = line;
 		this.column = column;
 	}
 
+	/**
+	 * Get the line (1-based) of this position.
+	 */
 	public int getLine() {
 		return this.line;
 	}
 
+	/**
+	 * Get the column (1-based) of this position.
+	 */
 	public int getColumn() {
 		return this.column;
 	}

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/FileSource.java

@@ -24,6 +24,9 @@
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * File based {@link org.junit.gen5.engine.TestSource} with an optional
+ * {@linkplain FilePosition position}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -34,10 +37,22 @@ public class FileSource implements FileSystemSource {
 	private final File file;
 	private final FilePosition filePosition;
 
+	/**
+	 * Create a new {@code FileSource} using the supplied {@link File file}.
+	 *
+	 * @param file the source file; must not be null
+	 */
 	public FileSource(File file) {
 		this(file, null);
 	}
 
+	/**
+	 * Create a new {@code FileSource} using the supplied {@link File file} and
+	 * {@link FilePosition position}.
+	 *
+	 * @param file the source file; must not be null
+	 * @param filePosition the source file; may be null
+	 */
 	public FileSource(File file, FilePosition filePosition) {
 		Preconditions.notNull(file, "file must not be null");
 		try {

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/FileSystemSource.java

@@ -15,13 +15,22 @@
 import java.io.File;
 
 import org.junit.gen5.commons.meta.API;
+import org.junit.gen5.engine.TestSource;
 
 /**
+ * File system based {@link TestSource}.
+ *
+ * <p>This interface uses {@link File} instead of {@link java.nio.file.Path}
+ * because the latter does not implement {@link java.io.Serializable}.
+ *
  * @since 5.0
  */
 @API(Experimental)
 public interface FileSystemSource extends UriSource {
 
+	/**
+	 * Get the source file or directory.
+	 */
 	File getFile();
 
 }

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/JavaClassSource.java

@@ -17,6 +17,8 @@
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * Java class based {@link org.junit.gen5.engine.TestSource}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -26,10 +28,19 @@ public class JavaClassSource implements JavaSource {
 
 	private final Class<?> javaClass;
 
+	/**
+	 * Create a new {@code JavaClassSource} using the supplied
+	 * {@link Class javaClass}.
+	 *
+	 * @param javaClass the Java class; must not be null
+	 */
 	public JavaClassSource(Class<?> javaClass) {
 		this.javaClass = Preconditions.notNull(javaClass, "class must not be null");
 	}
 
+	/**
+	 * Get the {@linkplain Class Java class} of this source.
+	 */
 	public final Class<?> getJavaClass() {
 		return this.javaClass;
 	}

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/JavaMethodSource.java

@@ -10,18 +10,25 @@
 
 package org.junit.gen5.engine.support.descriptor;
 
+import static java.util.Collections.unmodifiableList;
 import static org.junit.gen5.commons.meta.API.Usage.Experimental;
 import static org.junit.gen5.commons.util.StringUtils.nullSafeToString;
 
 import java.lang.reflect.Method;
 import java.util.Arrays;
+import java.util.List;
 import java.util.Objects;
 
 import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.commons.util.Preconditions;
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * Java method based {@link org.junit.gen5.engine.TestSource}.
+ *
+ * <p>This class stores the method name along with its parameter types because
+ * {@link Method} does not implement {@link java.io.Serializable}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -33,23 +40,44 @@ public class JavaMethodSource implements JavaSource {
 	private final String javaMethodName;
 	private final Class<?>[] javaMethodParameterTypes;
 
+	/**
+	 * Create a new {@code JavaMethodSource} using the supplied
+	 * {@link Method method}.
+	 *
+	 * @param method the Java method; must not be null
+	 */
 	public JavaMethodSource(Method method) {
 		Preconditions.notNull(method, "method must not be null");
 		this.javaClass = method.getDeclaringClass();
 		this.javaMethodName = method.getName();
 		this.javaMethodParameterTypes = method.getParameterTypes();
 	}
 
+	/**
+	 * Get the declaring {@linkplain Class class} of this source.
+	 *
+	 * @see Method#getDeclaringClass()
+	 */
 	public final Class<?> getJavaClass() {
 		return this.javaClass;
 	}
 
+	/**
+	 * Get the method name of this source.
+	 *
+	 * @see Method#getName()
+	 */
 	public final String getJavaMethodName() {
 		return this.javaMethodName;
 	}
 
-	public final Class<?>[] getJavaMethodParameterTypes() {
-		return this.javaMethodParameterTypes;
+	/**
+	 * Get the method's parameter types of this source.
+	 *
+	 * @see Method#getParameterTypes()
+	 */
+	public final List<Class<?>> getJavaMethodParameterTypes() {
+		return unmodifiableList(Arrays.asList(this.javaMethodParameterTypes));
 	}
 
 	@Override

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/JavaPackageSource.java

@@ -19,6 +19,11 @@
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
+ * Java package based {@link org.junit.gen5.engine.TestSource}.
+ *
+ * <p>This class stores the package name because {@link Package} does not
+ * implement {@link java.io.Serializable}.
+ *
  * @since 5.0
  */
 @API(Experimental)
@@ -28,14 +33,29 @@ public class JavaPackageSource implements JavaSource {
 
 	private final String packageName;
 
-	public JavaPackageSource(Package pkg) {
-		this(Preconditions.notNull(pkg, "package must not be null").getName());
+	/**
+	 * Create a new {@code JavaPackageSource} using the supplied
+	 * {@link Package javaPackage}.
+	 *
+	 * @param javaPackage the Java package; must not be null
+	 */
+	public JavaPackageSource(Package javaPackage) {
+		this(Preconditions.notNull(javaPackage, "package must not be null").getName());
 	}
 
+	/**
+	 * Create a new {@code JavaPackageSource} using the supplied
+	 * {@code packageName}.
+	 *
+	 * @param packageName the Java package name; must not be null or empty
+	 */
 	public JavaPackageSource(String packageName) {
 		this.packageName = Preconditions.notBlank(packageName, "package name must not be null or empty");
 	}
 
+	/**
+	 * Get the package name of this test source.
+	 */
 	public final String getPackageName() {
 		return this.packageName;
 	}

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/JavaSource.java

@@ -16,6 +16,9 @@
 import org.junit.gen5.engine.TestSource;
 
 /**
+ * Marker interface for {@link TestSource TestSources} that are based on
+ * elements of the Java language.
+ *
  * @since 5.0
  */
 @API(Experimental)

junit-engine-api/src/main/java/org/junit/gen5/engine/support/descriptor/UriSource.java

@@ -18,11 +18,16 @@
 import org.junit.gen5.engine.TestSource;
 
 /**
+ * A {@link TestSource} that can be represented as an {@link URI}.
+ *
  * @since 5.0
  */
 @API(Experimental)
 public interface UriSource extends TestSource {
 
+	/**
+	 * Get the {@link URI} that represents this source.
+	 */
 	URI getUri();
 
 }