[IO-857"][Javadoc] PathUtils.cleanDirectory() methods vs FileUtils.

Author: garydgregory

src/changes/changes.xml

@@ -67,6 +67,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action type="fix" dev="ggregory" due-to="Peter De Maeyer, Gary Gregory" issue="IO-885">Path visits follow links #832.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">BOMInputStream fail-fast and tracks its ByteOrderMark as a final #835.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Refactor UnixLineEndingInputStream and WindowsLineEndingInputStream for duplication.</action>
+      <action type="fix" dev="ggregory" due-to="Peter De Maeyer, Gary Gregory" issue="IO-857">[Javadoc] PathUtils.cleanDirectory() methods vs FileUtils.</action>
       <!-- ADD -->
       <action type="add" dev="ggregory" due-to="Gary Gregory, Piotr P. Karwasz">Add and use IOUtils.closeQuietlySuppress(Closeable, Throwable) #818.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyWriter.setReference(Writer).</action>

src/main/java/org/apache/commons/io/file/PathUtils.java

@@ -281,7 +281,10 @@ private static AccumulatorPathVisitor accumulate(final Path directory, final int
     }
 
     /**
-     * Cleans a directory by only deleting files, including in subdirectories, but without deleting the directories.
+     * Cleans a directory by only deleting files, including in subdirectories, without deleting directories.
+     * <p>
+     * This leaves a directory empty of files but the directory and any subdirectories remain.
+     * </p>
      *
      * @param directory directory to clean.
      * @return The visitation path counters.
@@ -292,7 +295,10 @@ public static PathCounters cleanDirectory(final Path directory) throws IOExcepti
     }
 
     /**
-     * Cleans a directory by only deleting files, including in subdirectories, but without deleting the directories.
+     * Cleans a directory by only deleting files, including in subdirectories, without deleting directories.
+     * <p>
+     * This leaves a directory empty of files but the directory and any subdirectories remain.
+     * </p>
      *
      * @param directory     directory to clean.
      * @param deleteOptions How to handle deletion.

src/test/java/org/apache/commons/io/file/PathUtilsCleanDirectoryTest.java

@@ -18,8 +18,10 @@
 package org.apache.commons.io.file;
 
 import static org.apache.commons.io.file.CounterAssertions.assertCounts;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.io.IOException;
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 
@@ -41,6 +43,7 @@ class PathUtilsCleanDirectoryTest {
     void testCleanDirectory1FileSize0() throws IOException {
         PathUtils.copyDirectory(Paths.get("src/test/resources/org/apache/commons/io/dirs-1-file-size-0"), tempDir);
         assertCounts(1, 1, 0, PathUtils.cleanDirectory(tempDir));
+        assertTrue(Files.exists(tempDir));
     }
 
     /**
@@ -50,6 +53,7 @@ void testCleanDirectory1FileSize0() throws IOException {
     void testCleanDirectory1FileSize1() throws IOException {
         PathUtils.copyDirectory(Paths.get("src/test/resources/org/apache/commons/io/dirs-1-file-size-1"), tempDir);
         assertCounts(1, 1, 1, PathUtils.cleanDirectory(tempDir));
+        assertTrue(Files.exists(tempDir));
     }
 
     /**
@@ -59,6 +63,7 @@ void testCleanDirectory1FileSize1() throws IOException {
     void testCleanDirectory2FileSize2() throws IOException {
         PathUtils.copyDirectory(Paths.get("src/test/resources/org/apache/commons/io/dirs-2-file-size-2"), tempDir);
         assertCounts(3, 2, 2, PathUtils.cleanDirectory(tempDir));
+        assertTrue(Files.exists(tempDir));
     }
 
     /**
@@ -67,5 +72,6 @@ void testCleanDirectory2FileSize2() throws IOException {
     @Test
     void testCleanEmptyDirectory() throws IOException {
         assertCounts(1, 0, 0, PathUtils.cleanDirectory(tempDir));
+        assertTrue(Files.exists(tempDir));
     }
 }