Clarify 'fragments' in JavaDocs for file manipulation operations

Author: ascopes

java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/PackageContainerGroupAssert.java

@@ -105,8 +105,16 @@ public ClassLoaderAssert classLoader() {
   /**
    * Assert that the given file does not exist.
    *
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   assertions.fileDoesNotExist("foo/bar/baz.txt")...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   assertions.fileDoesNotExist("foo", "bar", "baz.txt");
+   * </code></pre>
+   *
    * @param fragment  the first part of the path.
-   * @param fragments additional parts of the path.
+   * @param fragments any additional parts of the path.
    * @return this assertion object for further assertions.
    * @throws AssertionError       if the file exists, or if the container group is null.
    * @throws NullPointerException if any of the fragments are null.
@@ -138,8 +146,16 @@ public PackageContainerGroupAssert fileDoesNotExist(String fragment, String... f
   /**
    * Assert that the given file exists.
    *
-   * @param fragment  the path fragment.
-   * @param fragments any additional path fragments.
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   assertions.fileExists("foo/bar/baz.txt")...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   assertions.fileExists("foo", "bar", "baz.txt");
+   * </code></pre>
+   *
+   * @param fragment  the first part of the path.
+   * @param fragments any additional parts of the path.
    * @return assertions to perform on the path of the file that exists.
    * @throws AssertionError       if the file does not exist, or if the container group is null.
    * @throws NullPointerException if any of the fragments are null.

java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/Container.java

@@ -56,8 +56,18 @@ public interface Container extends Closeable {
   /**
    * Find the physical path to a given string file path.
    *
-   * @param fragment  the first fragment to the file to find.
-   * @param fragments any additional fragments to the file to find.
+   * <p>Examples:
+   *
+   * <pre><code>
+   *   // Using platform-specific separators ('/' for in-memory file systems).
+   *   container.getFile("foo/bar/baz.txt");
+   *
+   *   // Letting JCT infer the correct path separators to use.
+   *   container.getFile("foo", "bar", "baz.txt");
+   * </code></pre>
+   *
+   * @param fragment  the first part of the file name.
+   * @param fragments any additional parts of the file name to find.
    * @return the path if the file exists, or null if it does not exist.
    */
   @Nullable
@@ -121,6 +131,8 @@ public interface Container extends Closeable {
   /**
    * Get a module finder for this container.
    *
+   * <p>Note that this will not detect modules that are not yet compiled.
+   *
    * @return the module finder for this container, or {@code null} if not relevant to the
    *     implementation.
    */
@@ -161,8 +173,12 @@ public interface Container extends Closeable {
   /**
    * List all the file objects that match the given criteria in this group.
    *
+   * <p>The results are filled into a given collection, since this call may be made many times
+   * per compliation, and this reduces the memory overhead needed in such cases.
+   *
    * @param packageName the package name to look in.
-   * @param kinds       the kinds of file to look for.
+   * @param kinds       the kinds of file to look for. Set to {@code Set.of(Kind.OTHER)} to find
+   *                    all types of file.
    * @param recurse     {@code true} to recurse subpackages, {@code false} to only consider the
    *                    given package.
    * @param collection  the collection to fill.

java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/PackageContainerGroup.java

@@ -84,6 +84,14 @@ public interface PackageContainerGroup extends ContainerGroup {
    *
    * <p>Modules are treated as subdirectories.
    *
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   containerGroup.getFile("foo/bar/baz.txt")...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   containerGroup.getFile("foo", "bar", "baz.txt");
+   * </code></pre>
+   *
    * @param fragment  the first part of the path.
    * @param fragments any additional parts of the path.
    * @return the first occurrence of the path in this group, or null if not found.

java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/FileUtils.java

@@ -258,8 +258,8 @@ public static Path resourceNameToPath(Path directory, String packageName, String
    * Convert a relative class path resource path to a NIO path.
    *
    * @param directory the directory the resource sits within.
-   * @param fragment  the first path fragment.
-   * @param fragments any additional path fragments.
+   * @param fragment  the first part of the path.
+   * @param fragments the rest of the path.
    * @return the path to the resource on the file system.
    */
   public static Path relativeResourceNameToPath(

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

@@ -38,8 +38,18 @@ public interface DirectoryBuilder {
    *
    * <p>This uses the default file system.
    *
-   * @param first the first path fragment of the directory to copy from.
-   * @param rest  any additional path fragments to copy from.
+   * <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");
+   * </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.
    */
   ManagedDirectory copyContentsFrom(String first, String... rest);

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

@@ -75,8 +75,18 @@ default ManagedDirectory and() {
   /**
    * Create a directory builder for the given path in this RAM file system.
    *
-   * @param first the first path fragment.
-   * @param rest  any additional path fragments.
+   * <p>Examples:
+   *
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   dir.createDirectory("foo/bar/baz")...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   dir.createDirectory("foo", "bar", "baz")...;
+   * </code></pre>
+   *
+   * @param first the first part of the path.
+   * @param rest  any additional parts of the path.
    * @return the directory builder.
    */
   @CheckReturnValue
@@ -85,12 +95,20 @@ default ManagedDirectory and() {
   /**
    * Create a file builder for the given path in this RAM file system.
    *
-   * @param first the first path fragment.
-   * @param rest  any additional path fragments.
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   dir.createFile("foo/bar/baz.txt")...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   dir.createFile("foo", "bar", "baz.txt")...;
+   * </code></pre>
+   *
+   * @param fragment the first part of the path.
+   * @param fragments  any additional parts of the path.
    * @return the file builder.
    */
   @CheckReturnValue
-  FileBuilder createFile(String first, String... rest);
+  FileBuilder createFile(String fragment, String... fragments);
 
   /**
    * Get the identifying name of the temporary file system.

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

@@ -104,8 +104,8 @@ public String getName() {
 
   @CheckReturnValue
   @Override
-  public FileBuilder createFile(String first, String... rest) {
-    return new FileBuilderImpl(this, first, rest);
+  public FileBuilder createFile(String fragment, String... fragments) {
+    return new FileBuilderImpl(this, fragment, fragments);
   }
 
   @CheckReturnValue