Add Javadoc

Author: marcphilipp

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtensionContext.java

@@ -371,8 +371,8 @@ default void publishReportEntry(String value) {
 	 * Publish a file with the supplied name written by the supplied action and
 	 * attach it to the current test or container.
 	 * <p>
-	 * The file will be located in the report output directory prior to invoking
-	 * the supplied action.
+	 * The file will be resolved in the report output directory prior to
+	 * invoking the supplied action.
 	 *
 	 * @param fileName the name of the file to be attached; never {@code null} or blank
 	 *                 and must not contain any path separators

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

@@ -10,6 +10,7 @@
 
 package org.junit.platform.engine;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.util.List;
@@ -74,10 +75,6 @@ public interface EngineDiscoveryRequest {
 	/**
 	 * Get the {@link EngineDiscoveryListener} for this request.
 	 *
-	 * <p>The default implementation returns a no-op listener that ignores all
-	 * calls so that engines that call this methods can be used with an earlier
-	 * version of the JUnit Platform that did not yet include this API.
-	 *
 	 * @return the discovery listener; never {@code null}
 	 * @since 1.6
 	 */
@@ -86,6 +83,13 @@ default EngineDiscoveryListener getDiscoveryListener() {
 		return EngineDiscoveryListener.NOOP;
 	}
 
+	/**
+	 * Get the {@link OutputDirectoryProvider} for this request.
+	 *
+	 * @return the output directory provider; never {@code null}
+	 * @since 1.12
+	 */
+	@API(status = EXPERIMENTAL, since = "1.12")
 	default OutputDirectoryProvider getOutputDirectoryProvider() {
 		throw new JUnitException(
 			"OutputDirectoryProvider not available; probably due to unaligned versions of the junit-platform-engine and junit-platform-launcher jars on the classpath/module path.");

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

@@ -139,6 +139,23 @@ default void executionFinished(TestDescriptor testDescriptor, TestExecutionResul
 	default void reportingEntryPublished(TestDescriptor testDescriptor, ReportEntry entry) {
 	}
 
+	/**
+	 * Can be called for any {@link TestDescriptor} in order to attach a file to
+	 * a test or container — for example:
+	 *
+	 * <ul>
+	 *     <li>Screenshots</li>
+	 *     <li>Logs</li>
+	 *     <li>Output files written by the code under test</li>
+	 * </ul>
+	 *
+	 * <p>The current lifecycle state of the supplied {@code TestDescriptor} is
+	 * not relevant: file events can occur at any time.
+	 *
+	 * @param testDescriptor the descriptor of the test or container to which
+	* the file entry belongs
+	 * @param file a {@code FileEntry} instance to be attached
+	 */
 	@API(status = EXPERIMENTAL, since = "1.12")
 	default void fileEntryPublished(TestDescriptor testDescriptor, FileEntry file) {
 	}

junit-platform-engine/src/main/java/org/junit/platform/engine/reporting/FileEntry.java

@@ -20,12 +20,13 @@
 import org.junit.platform.commons.util.ToStringBuilder;
 
 /**
- * {@code FileEntry} encapsulates a file to be published to the reporting infrastructure.
+ * {@code FileEntry} encapsulates a file to be published to the reporting
+ * infrastructure.
  *
- * @since 1.11
+ * @since 1.12
  * @see #from(Path)
  */
-@API(status = EXPERIMENTAL, since = "1.11")
+@API(status = EXPERIMENTAL, since = "1.12")
 public final class FileEntry {
 
 	/**
@@ -53,6 +54,11 @@ public LocalDateTime getTimestamp() {
 		return this.timestamp;
 	}
 
+	/**
+	 * Get the file to be published.
+	 *
+	 * @return the file to publish; never {@code null}
+	 */
 	public Path getFile() {
 		return file;
 	}

junit-platform-engine/src/main/java/org/junit/platform/engine/reporting/OutputDirectoryProvider.java

@@ -16,13 +16,32 @@
 import java.nio.file.Path;
 
 import org.apiguardian.api.API;
+import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.engine.TestDescriptor;
 
+/**
+ * Provider of output directories for test engines to write reports and other
+ * output files to.
+ *
+ * @since 1.12
+ * @see EngineDiscoveryRequest#getOutputDirectoryProvider()
+ */
 @API(status = EXPERIMENTAL, since = "1.12")
 public interface OutputDirectoryProvider {
 
+	/**
+	 * {@return the root directory for all output files}
+	 */
 	Path getRootDirectory();
 
+	/**
+	 * Create an output directory for the supplied test descriptor.
+	 *
+	 * @param testDescriptor the test descriptor for which to create an output
+	 *                       directory
+	 * @return the output directory
+	 * @throws IOException if the output directory could not be created
+	 */
 	Path createOutputDirectory(TestDescriptor testDescriptor) throws IOException;
 
 }

junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java

@@ -191,8 +191,32 @@ public class LauncherConstants {
 	@API(status = EXPERIMENTAL, since = "1.10")
 	public static final String STACKTRACE_PRUNING_ENABLED_PROPERTY_NAME = "junit.platform.stacktrace.pruning.enabled";
 
+	/**
+	 * Property name used to configure the output directory for reporting.
+	 *
+	 * <p>If set, value must be a valid path that will be created if it doesn't
+	 * exist. If not set, the default output directory will be determined by the
+	 * reporting engine based on the current working directory.
+	 *
+	 * @since 1.12
+	 * @see #OUTPUT_DIR_UNIQUE_NUMBER_PLACEHOLDER
+	 * @see org.junit.platform.engine.reporting.OutputDirectoryProvider
+	 */
+	@API(status = EXPERIMENTAL, since = "1.12")
 	public static final String OUTPUT_DIR_PROPERTY_NAME = "junit.platform.reporting.output.dir";
 
+	/**
+	 * Placeholder for use in {@link #OUTPUT_DIR_PROPERTY_NAME} that will be
+	 * replaced with a unique number.
+	 *
+	 * <p>This can be used to create a unique output directory for each test
+	 * run. For example, if multiple forks are used, each fork can be configured
+	 * to write its output to a separate directory.
+	 *
+	 * @since 1.12
+	 * @see #OUTPUT_DIR_PROPERTY_NAME
+	 */
+	@API(status = EXPERIMENTAL, since = "1.12")
 	public static final String OUTPUT_DIR_UNIQUE_NUMBER_PLACEHOLDER = "{uniqueNumber}";
 
 	private LauncherConstants() {