Deprecate modules in JavacCompilerTest annotation, add examples to junit package

Author: ascopes

java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/JavacCompilerTest.java

@@ -33,9 +33,8 @@
 import org.junit.jupiter.params.provider.ArgumentsSource;
 
 /**
- * Annotation that can be applied to a {@link ParameterizedTest} to enable passing in a range of
- * {@link JavacJctCompilerImpl} instances with specific configured versions as the  first
- * parameter.
+ * Annotation that can be applied to a JUnit parameterized test to invoke that test case across
+ * multiple compilers, each configured to a specific version in a range of Java language versions.
  *
  * <p>This will also add the {@code "java-compiler-testing-test"} tag and {@code "javac-test"}
  * tags to your test method, meaning you can instruct your IDE or build system to optionally only
@@ -45,6 +44,35 @@
  * <p>If your build is running in a GraalVM Native Image, then this test will not execute, as
  * the <em>Java Compiler Testing</em> API is not yet tested within Native Images.
  *
+ * <p>For example, to run a simple test on Java 11 through 17 (inclusive):
+ *
+ * <pre><code>
+ *   class SomeTest {
+ *     {@literal @JavacCompilerTest(minVersion = 11, maxVersion = 17)}
+ *     void canCompileHelloWorld(JctCompiler&lt;?, ?&gt;> compiler) {
+ *       // Given
+ *       try (var workspace = Workspaces.newWorkspace()) {
+ *         workspace
+ *            .createFile("org", "example", "HelloWorld.java")
+ *            .withContents("""
+ *              package org.example;
+ *
+ *              public class HelloWorld {
+ *                public static void main(String[] args) {
+ *                  System.out.println("Hello, World!");
+ *                }
+ *              }
+ *            """);
+ *
+ *         var compilation = compiler.compile(workspace);
+ *
+ *         assertThat(compilation)
+ *             .isSuccessfulWithoutWarnings();
+ *       }
+ *     }
+ *   }
+ * </code></pre>
+ *
  * @author Ashley Scopes
  * @since 0.0.1
  */
@@ -66,19 +94,35 @@
   /**
    * Minimum version to use (inclusive).
    *
+   * <p>By default, it will use the lowest possible version supported by the compiler. This
+   * varies between versions of the JDK that are in use.
+   *
+   * <p>If the version is lower than the minimum supported version, then the minimum supported
+   * version of the compiler will be used instead. This enables writing tests that will work on
+   * a range of JDKs during builds without needing to duplicate the test to satisfy different
+   * JDK supported version ranges.
+   *
    * @return the minimum version.
    */
   int minVersion() default Integer.MIN_VALUE;
 
   /**
    * Maximum version to use (inclusive).
    *
+   * <p>By default, it will use the highest possible version supported by the compiler. This
+   * varies between versions of the JDK that are in use.
+   *
+   * <p>If the version is higher than the maximum supported version, then the maximum supported
+   * version of the compiler will be used instead. This enables writing tests that will work on
+   * a range of JDKs during builds without needing to duplicate the test to satisfy different
+   * JDK supported version ranges.
+   *
    * @return the maximum version.
    */
   int maxVersion() default Integer.MAX_VALUE;
 
   /**
-   * Get an array of compiler configurers to apply in-order before starting the test.
+   * Get an array of compiler configurer classes to apply in-order before starting the test.
    *
    * <p>Each configurer must have a public no-args constructor, and their package must be
    * open to this module if JPMS modules are in-use, for example:
@@ -92,6 +136,26 @@
    * }
    * </code></pre>
    *
+   * An example of usage:
+   *
+   * <pre><code>
+   *   public class WerrorConfigurer implements JctCompilerConfigurer&lt;RuntimeException&gt; {
+   *     {@literal @Override}
+   *     public void configure(JctCompiler&lt;?, ?&gt; compiler) {
+   *       compiler.failOnWarnings(true);
+   *     }
+   *   }
+   *
+   *   // ...
+   *
+   *   class SomeTest {
+   *     {@literal @JavacCompilerTest(configurers = WerrorConfigurer.class)}
+   *     void someTest(JctCompiler&lt;?, ?&gt; compiler) {
+   *       // ...
+   *     }
+   *   }
+   * </code></pre>
+   *
    * @return an array of classes to run to configure the compiler. These run in the given order.
    */
   Class<? extends JctCompilerConfigurer<?>>[] configurers() default {};
@@ -103,7 +167,9 @@
    * modules.
    *
    * @return {@code true} if we need to support modules, or {@code false} if we do not.
+   * @deprecated this will be removed in a future release, since Java 8 is reaching end-of-life.
    */
+  @Deprecated(forRemoval = true, since = "0.0.2")
   boolean modules() default false;
 
   /**

java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/JavacCompilersProvider.java

@@ -59,6 +59,7 @@ protected int maxSupportedVersion(boolean modules) {
   }
 
   @Override
+  @SuppressWarnings("removal")
   public void accept(JavacCompilerTest javacCompilers) {
     // Super is needed here to prevent IntelliJ getting confused.
     super.configure(

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/DirectoryBuilder.java

@@ -16,6 +16,7 @@
 package io.github.ascopes.jct.workspaces;
 
 import java.io.File;
+import java.nio.file.FileSystem;
 import java.nio.file.Path;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
@@ -32,27 +33,40 @@ public interface DirectoryBuilder {
   /**
    * Copy the contents of the directory at the given path recursively into this directory.
    *
-   * <p>This uses the default file system.
+   * <p>Symbolic links will not be followed.
+   *
+   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
+   * as your source, then use {@link #copyContentsFrom(Path)} instead.
    *
    * <p>Examples:
    *
    * <pre><code>
-   *   // Using platform-specific separators.
-   *   directoryBuilder.copyContentsFrom("foo/bar/baz");
-   *
    *   // Letting JCT infer the correct path separators to use (recommended).
    *   directoryBuilder.copyContentsFrom("foo", "bar", "baz");
+   *
+   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
+   *   directoryBuilder.copyContentsFrom("foo/bar/baz");
+   *
+   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
+   *   directoryBuilder.copyContentsFrom("foo\\bar\\baz");
    * </code></pre>
    *
    * @param first the first part of the path to the directory to copy from.
    * @param rest  any additional parts of the path.
    * @return the root managed directory for further configuration.
+   * @see #copyContentsFrom(Path)
    */
   ManagedDirectory copyContentsFrom(String first, String... rest);
 
   /**
    * Copy the contents of the directory at the given path recursively into this directory.
    *
+   * <p>Symbolic links will not be followed.
+   *
+   * <pre><code>
+   *  directory.copyContentsFrom(new File("code/examples"));
+   * </code></pre>
+   *
    * @param dir the directory to copy the contents from.
    * @return the root managed directory for further configuration.
    */
@@ -61,6 +75,12 @@ public interface DirectoryBuilder {
   /**
    * Copy the contents of the directory at the given path recursively into this directory.
    *
+   * <p>Symbolic links will not be followed.
+   *
+   * <pre><code>
+   *   directory.copyContentsFrom(Path.of("code", "examples"));
+   * </code></pre>
+   *
    * @param rootDir the directory to copy the contents from.
    * @return the root managed directory for further configuration.
    */
@@ -69,6 +89,10 @@ public interface DirectoryBuilder {
   /**
    * Create an empty directory.
    *
+   * <pre><code>
+   *   directory.thatIsEmpty();
+   * </code></pre>
+   *
    * @return the root managed directory for further configuration.
    */
   ManagedDirectory thatIsEmpty();