1 files changed, 48 insertions, 12 deletions
diff --git a/src/main/java/org/apache/commons/io/file/FilesUncheck.java b/src/main/java/org/apache/commons/io/file/FilesUncheck.java
index 02a1febb..02688cac 100644
--- a/src/main/java/org/apache/commons/io/file/FilesUncheck.java
+++ b/src/main/java/org/apache/commons/io/file/FilesUncheck.java
@@ -22,6 +22,7 @@ import java.io.BufferedWriter;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.Reader;
 import java.io.UncheckedIOException;
 import java.nio.channels.SeekableByteChannel;
 import java.nio.charset.Charset;
@@ -244,6 +245,10 @@ public final class FilesUncheck {
 
     /**
      * Delegates to {@link Files#find(Path, int, BiPredicate, FileVisitOption...)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} wraps a {@link DirectoryStream}. When you require timely disposal of file system resources, use a {@code try}-with-resources
+     * block to ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed.
+     * </p>
      *
      * @param start    See delegate.
      * @param maxDepth See delegate.
@@ -348,6 +353,10 @@ public final class FilesUncheck {
 
     /**
      * Delegates to {@link Files#lines(Path)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} wraps a {@link Reader}. When you require timely disposal of file system resources, use a {@code try}-with-resources block to
+     * ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed.
+     * </p>
      *
      * @param path See delegate.
      * @return See delegate.
@@ -359,6 +368,10 @@ public final class FilesUncheck {
 
     /**
      * Delegates to {@link Files#lines(Path, Charset)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} wraps a {@link Reader}. When you require timely disposal of file system resources, use a {@code try}-with-resources block to
+     * ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed.
+     * </p>
      *
      * @param path See delegate.
      * @param cs See delegate.
@@ -371,6 +384,10 @@ public final class FilesUncheck {
 
     /**
      * Delegates to {@link Files#list(Path)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} wraps a {@link DirectoryStream}. When you require timely disposal of file system resources, use a {@code try}-with-resources
+     * block to ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed.
+     * </p>
      *
      * @param dir See delegate.
      * @return See delegate.
@@ -474,8 +491,11 @@ public final class FilesUncheck {
     }
 
     /**
-     * Delegates to {@link Files#newDirectoryStream(Path)} throwing {@link UncheckedIOException} instead of
-     * {@link IOException}.
+     * Delegates to {@link Files#newDirectoryStream(Path)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * If you don't use the try-with-resources construct, then you must call the stream's {@link Stream#close()} method after iteration is complete to free any
+     * resources held for the open directory.
+     * </p>
      *
      * @param dir See delegate.
      * @return See delegate.
@@ -485,10 +505,14 @@ public final class FilesUncheck {
     }
 
     /**
-     * Delegates to {@link Files#newDirectoryStream(Path, java.nio.file.DirectoryStream.Filter)} throwing
-     * {@link UncheckedIOException} instead of {@link IOException}.
+     * Delegates to {@link Files#newDirectoryStream(Path, java.nio.file.DirectoryStream.Filter)} throwing {@link UncheckedIOException} instead of
+     * {@link IOException}.
+     * <p>
+     * If you don't use the try-with-resources construct, then you must call the stream's {@link Stream#close()} method after iteration is complete to free any
+     * resources held for the open directory.
+     * </p>
      *
-     * @param dir See delegate.
+     * @param dir    See delegate.
      * @param filter See delegate.
      * @return See delegate.
      */
@@ -499,6 +523,10 @@ public final class FilesUncheck {
     /**
      * Delegates to {@link Files#newDirectoryStream(Path, String)} throwing {@link UncheckedIOException} instead of
      * {@link IOException}.
+     * <p>
+     * The returned {@link Stream} wraps a {@link DirectoryStream}. When you require timely disposal of file system resources, use a {@code try}-with-resources
+     * block to ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed.
+     * </p>
      *
      * @param dir See delegate.
      * @param glob See delegate.
@@ -674,10 +702,14 @@ public final class FilesUncheck {
     }
 
     /**
-     * Delegates to {@link Files#walk(Path, FileVisitOption...)} throwing {@link UncheckedIOException} instead of
-     * {@link IOException}.
+     * Delegates to {@link Files#walk(Path, FileVisitOption...)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} may wrap one or more {@link DirectoryStream}s. When you require timely disposal of file system resources, use a
+     * {@code try}-with-resources block to ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed. Calling a
+     * closed stream causes a {@link IllegalStateException}.
+     * </p>
      *
-     * @param start See delegate.
+     * @param start   See delegate.
      * @param options See delegate.
      * @return See delegate.
      */
@@ -686,12 +718,16 @@ public final class FilesUncheck {
     }
 
     /**
-     * Delegates to {@link Files#walk(Path, int, FileVisitOption...)} throwing {@link UncheckedIOException} instead of
-     * {@link IOException}.
+     * Delegates to {@link Files#walk(Path, int, FileVisitOption...)} throwing {@link UncheckedIOException} instead of {@link IOException}.
+     * <p>
+     * The returned {@link Stream} may wrap one or more {@link DirectoryStream}s. When you require timely disposal of file system resources, use a
+     * {@code try}-with-resources block to ensure invocation of the stream's {@link Stream#close()} method after the stream operations are completed. Calling a
+     * closed stream causes a {@link IllegalStateException}.
+     * </p>
      *
-     * @param start See delegate.
+     * @param start    See delegate.
      * @param maxDepth See delegate.
-     * @param options See delegate.
+     * @param options  See delegate.
      * @return See delegate.
      */
     public static Stream<Path> walk(final Path start, final int maxDepth, final FileVisitOption... options) {