Add Javadoc and API annotations to dynamic test classes (#58)

junit-engine-api/src/main/java/org/junit/gen5/engine/support/hierarchical/SingleTestExecutor.java

@@ -10,17 +10,23 @@
 
 package org.junit.gen5.engine.support.hierarchical;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
 import static org.junit.gen5.engine.TestExecutionResult.aborted;
 import static org.junit.gen5.engine.TestExecutionResult.failed;
 import static org.junit.gen5.engine.TestExecutionResult.successful;
 import static org.junit.gen5.engine.support.hierarchical.BlacklistedExceptions.rethrowIfBlacklisted;
 
+import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.engine.TestExecutionResult;
 import org.opentest4j.TestAbortedException;
 
 /**
+ * Executes a single test wrapped in an {@link Executable} and returns a
+ * {@link TestExecutionResult} by converting exceptions.
+ *
  * @since 5.0
  */
+@API(Experimental)
 public class SingleTestExecutor {
 
 	public interface Executable {

junit5-api/src/main/java/org/junit/gen5/api/DynamicTest.java

@@ -10,6 +10,8 @@
 
 package org.junit.gen5.api;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
 import java.util.Iterator;
 import java.util.Spliterator;
 import java.util.Spliterators;
@@ -18,6 +20,24 @@
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
+import org.junit.gen5.commons.meta.API;
+
+/**
+ * A {@code DynamicTest} is a test case generated at runtime.
+ *
+ * <p>It is composed of a name and an {@code Executable}.
+ * Instances of {@code DynamicTest} must be generated by factory methods
+ * denoted by {@link TestFactory @TestFactory}.
+ * They allow for simple dynamic tests.
+ * Note that such tests are quite different from standard {@link Test} cases
+ * as the former do not execute callbacks like {@link BeforeEach} and {@link AfterEach}.
+ *
+ * @since 5.0
+ * @see Test
+ * @see TestFactory
+ * @see Executable
+ */
+@API(Experimental)
 public class DynamicTest {
 
 	private final String name;

junit5-api/src/main/java/org/junit/gen5/api/TestFactory.java

@@ -20,6 +20,27 @@
 
 import org.junit.gen5.commons.meta.API;
 
+/**
+ * {@code @TestFactory} is used to signal that the annotated method is a
+ * <em>test factory</em> method.
+ *
+ * <p>In contrast to {@link Test @Test} it is not itself a test case but
+ * creates test cases. Such a {@link TestFactory @TestFactory} method must
+ * return a {@code Stream} or {@code Iterable} of {@link DynamicTest}
+ * instances.
+ * These {@link DynamicTest DynamicTests} will then be executed lazily
+ * enabling dynamic and even non-deterministic generation of test cases.
+ *
+ * <p>{@code @TestFactory} methods must not be {@code private} or {@code static}.
+ *
+ * <p>{@code @TestFactory} methods may optionally declare parameters to be
+ * resolved by {@link org.junit.gen5.api.extension.MethodParameterResolver
+ * MethodParameterResolvers}.
+ *
+ * @since 5.0
+ * @see Test
+ * @see DynamicTest
+ */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
 @Documented

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/descriptor/DynamicTestTestDescriptor.java

@@ -10,11 +10,21 @@
 
 package org.junit.gen5.engine.junit5.descriptor;
 
+import static org.junit.gen5.commons.meta.API.Usage.Internal;
+
 import org.junit.gen5.api.DynamicTest;
+import org.junit.gen5.commons.meta.API;
+import org.junit.gen5.engine.TestDescriptor;
 import org.junit.gen5.engine.TestSource;
 import org.junit.gen5.engine.UniqueId;
 import org.junit.gen5.engine.support.descriptor.AbstractTestDescriptor;
 
+/**
+ * {@link TestDescriptor} for dynamic tests.
+ *
+ * @since 5.0
+ */
+@API(Internal)
 public class DynamicTestTestDescriptor extends AbstractTestDescriptor {
 
 	private final DynamicTest dynamicTest;

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/descriptor/TestFactoryTestDescriptor.java

@@ -28,6 +28,7 @@
 import org.junit.gen5.commons.JUnitException;
 import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.engine.EngineExecutionListener;
+import org.junit.gen5.engine.TestDescriptor;
 import org.junit.gen5.engine.TestExecutionResult;
 import org.junit.gen5.engine.UniqueId;
 import org.junit.gen5.engine.junit5.execution.JUnit5EngineExecutionContext;
@@ -36,6 +37,11 @@
 import org.junit.gen5.engine.support.hierarchical.Leaf;
 import org.junit.gen5.engine.support.hierarchical.SingleTestExecutor;
 
+/**
+ * {@link TestDescriptor} for test factory methods.
+ *
+ * @since 5.0
+ */
 @API(Internal)
 public class TestFactoryTestDescriptor extends MethodTestDescriptor implements Leaf<JUnit5EngineExecutionContext> {
 

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/discovery/IsTestFactoryMethod.java

@@ -23,7 +23,7 @@
 import org.junit.gen5.commons.meta.API;
 
 /**
- * Test if a method is a JUnit 5 test method.
+ * Test if a method is a JUnit 5 test factory method.
  *
  * @since 5.0
  */

junit5-engine/src/main/java/org/junit/gen5/engine/junit5/discovery/TestFactoryMethodResolver.java

@@ -10,13 +10,30 @@
 
 package org.junit.gen5.engine.junit5.discovery;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
 import java.lang.reflect.Method;
 
+import org.junit.gen5.api.TestFactory;
+import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.engine.TestDescriptor;
 import org.junit.gen5.engine.UniqueId;
 import org.junit.gen5.engine.junit5.descriptor.ClassTestDescriptor;
 import org.junit.gen5.engine.junit5.descriptor.TestFactoryTestDescriptor;
 
+/**
+ * {@code TestFactoryMethodResolver} is a special {@link ElementResolver}
+ * which is able to resolve test factory methods denoted by
+ * {@link TestFactory @TestFactory}.
+ *
+ * <p>It will create {@link TestFactoryTestDescriptor} instances.
+ *
+ * @since 5.0
+ * @see ElementResolver
+ * @see TestFactory
+ * @see TestFactoryTestDescriptor
+ */
+@API(Experimental)
 public class TestFactoryMethodResolver extends TestMethodResolver {
 
 	public static final String SEGMENT_TYPE = "test-factory";