[IO-857] Javadoc: Update details for PathUtils "clean" behavior

Author: garydgregory

src/changes/changes.xml

@@ -57,7 +57,8 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix" issue="IO-859" due-to="JD Dean, Gary Gregory">FileUtils.forceDelete on non-existent file on Windows throws IOException rather than FileNotFoundException.</action>
       <action dev="ggregory" type="fix"                due-to="Éamonn McManus">Use Unicode escapes for superscript characters. #701.</action>
       <action dev="ggregory" type="fix" issue="IO-863" due-to="Éamonn McManus, Gary Gregory">Recent incompatible change to FileUtils.listFiles re extensions, see IO-856.</action>
-      <action dev="ggregory" type="fix" issue="IO-862" due-to="Éamonn McManus, Gary Gregory">FileUtils.deleteDirectory fails for a directory containing a broken symbolic link.</action>
+      <action dev="ggregory" type="fix" issue="IO-857" due-to="Dmitry, Gary Gregory">Javadoc: Update details for PathUtils "clean" behavior.</action>
+      
       <!-- ADD -->
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add @FunctionalInterface to ClassNameMatcher.</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ValidatingObjectInputStream.Builder and ValidatingObjectInputStream.builder().</action>

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

@@ -57,7 +57,7 @@ public static CountingPathVisitor withLongCounters() {
     private final boolean overrideReadOnly;
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param deleteOption How deletion is handled.
@@ -73,7 +73,7 @@ public CleaningPathVisitor(final PathCounters pathCounter, final DeleteOption[]
     }
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a new instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param skip The files to skip deleting.

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

@@ -45,7 +45,7 @@ private static CopyOption[] toCopyOption(final CopyOption... copyOptions) {
     private final Path targetDirectory;
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param sourceDirectory The source directory
@@ -60,7 +60,7 @@ public CopyDirectoryVisitor(final PathCounters pathCounter, final Path sourceDir
     }
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param fileFilter How to filter file paths.

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

@@ -59,7 +59,7 @@ public static DeletingPathVisitor withLongCounters() {
     private final LinkOption[] linkOptions;
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param deleteOption How deletion is handled.
@@ -71,7 +71,7 @@ public DeletingPathVisitor(final PathCounters pathCounter, final DeleteOption[]
     }
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      * @param linkOptions How symbolic links are handled.
@@ -90,7 +90,7 @@ public DeletingPathVisitor(final PathCounters pathCounter, final LinkOption[] li
     }
 
     /**
-     * Constructs a new visitor that deletes files except for the files and directories explicitly given.
+     * Constructs a instance that deletes files except for the files and directories explicitly given.
      *
      * @param pathCounter How to count visits.
      *

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

@@ -227,7 +227,7 @@ private static AccumulatorPathVisitor accumulate(final Path directory, final int
     }
 
     /**
-     * Cleans a directory including subdirectories without deleting directories.
+     * Cleans a directory by deleting only files, including in subdirectories, but without deleting the directories.
      *
      * @param directory directory to clean.
      * @return The visitation path counters.
@@ -238,7 +238,7 @@ public static PathCounters cleanDirectory(final Path directory) throws IOExcepti
     }
 
     /**
-     * Cleans a directory including subdirectories without deleting directories.
+     * Cleans a directory by deleting only files, including in subdirectories, but without deleting the directories.
      *
      * @param directory     directory to clean.
      * @param deleteOptions How to handle deletion.