From 3e9403ef3917095fc30533ebc5d96dc23f2b0c58 Mon Sep 17 00:00:00 2001
From: Greg Wilkins <gregw@webtide.com>
Date: Tue, 22 Nov 2022 18:39:03 +1100
Subject: [PATCH] improved javadoc

Signed-off-by: Greg Wilkins <gregw@webtide.com>
---
 .../jetty/util/resource/CombinedResource.java |  8 +++++---
 .../eclipse/jetty/util/resource/Resource.java | 10 ++++++----
 .../jetty/util/resource/ResourceFactory.java  | 20 +++++++++++++------
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/CombinedResource.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/CombinedResource.java
index e264e06d9d1..5c0faf8c94c 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/CombinedResource.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/CombinedResource.java
@@ -32,9 +32,11 @@ import org.eclipse.jetty.util.URIUtil;
 public class CombinedResource extends Resource
 {
     /**
-     * <p>Make a Resource containing a combination of other resources</p>
-     * @param resources multiple resources to combine as a single resource. Typically, they are directories.
-     * @return A Resource of multiple resources or a single resource if only 1 is passed, or null if none are passed
+     * <p>Make a Resource containing a combination of multiple directory resources.</p>
+     * @param resources multiple directory resources to combine as a single resource. Order is significant.
+     * @return A Resource of multiple resources or a single resource if only 1 is passed, or null if none are passed.
+     *         Any Resource returned will always return {@code true} from {@link Resource#isDirectory()}
+     * @throws IllegalArgumentException if a non-directory resource is passed.
      * @see CombinedResource
      */
     static Resource combine(List<Resource> resources)
diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
index 302ef729241..1aa859b0715 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
@@ -221,12 +221,14 @@ public abstract class Resource implements Iterable<Resource>
     }
 
     /**
-     * <p>List of existing Resources contained in the given resource.</p>
+     * <p>List of contents of a directory {@link Resource}.</p>
      *
-     * <p>Ordering is unspecified, so callers may wish to sort the return value to ensure deterministic behavior.</p>
+     * <p>Ordering is {@link java.nio.file.FileSystem} dependent, so callers may wish to sort the return value to ensure deterministic behavior.</p>
      *
-     * @return a mutable list of resources contained in the tracked resource,
-     * or an empty immutable list if unable to build the list.
+     * @return a mutable list of resources contained in the directory resource,
+     * or an empty immutable list if unable to build the list  (e.g. the resource is not a directory or not readable).
+     * @see Resource#isDirectory()
+     * @see Resource#isReadable()
      */
     public List<Resource> list()
     {
diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceFactory.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceFactory.java
index cf6f6acb2f7..5b0d0368951 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceFactory.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceFactory.java
@@ -33,9 +33,13 @@ import org.eclipse.jetty.util.component.Dumpable;
 public interface ResourceFactory
 {
     /**
-     * <p>Make a Resource containing a collection of other resources</p>
-     * @param resources multiple resources to combine as a single resource. Typically, they are directories.
-     * @return A Resource of multiple resources or a single resource if only 1 is passed, or null if none are passed
+     * <p>Make a directory Resource containing a collection of other directory {@link Resource}s</p>
+     * @param resources multiple directory {@link Resource}s to combine as a single resource. Order is significant.
+     * @return A {@link CombinedResource} for multiple resources;
+     *         or a single {@link Resource} if only 1 is passed;
+     *         or null if none are passed.
+     *         The returned {@link Resource} will always return {@code true} from {@link Resource#isDirectory()}
+     * @throws IllegalArgumentException if a non-directory resource is passed.
      * @see CombinedResource
      */
     static Resource combine(List<Resource> resources)
@@ -44,9 +48,13 @@ public interface ResourceFactory
     }
 
     /**
-     * <p>Make a Resource containing a collection of other resources</p>
-     * @param resources multiple resources to combine as a single resource. Typically, they are directories.
-     * @return A Resource of multiple resources.
+     * <p>Make a directory Resource containing a collection of directory {@link Resource}s</p>
+     * @param resources multiple directory {@link Resource}s to combine as a single resource. Order is significant.
+     * @return A {@link CombinedResource} for multiple resources;
+     *         or a single {@link Resource} if only 1 is passed;
+     *         or null if none are passed.
+     *         The returned {@link Resource} will always return {@code true} from {@link Resource#isDirectory()}
+     * @throws IllegalArgumentException if a non-directory resource is passed.
      * @see CombinedResource
      */
     static Resource combine(Resource... resources)