Javadoc and refactor to FileTimes.now().

Reuse own APIs.

Author: Gary Gregory

src/main/java/org/apache/commons/io/FileSystem.java

@@ -288,6 +288,7 @@ public int getMaxPathLength() {
 
     /**
      * Gets the name separator, '\\' on Windows, '/' on Linux.
+     *
      * @return '\\' on Windows, '/' on Linux.
      *
      * @since 2.12.0
@@ -372,7 +373,7 @@ public boolean isReservedFileName(final CharSequence candidate) {
     /**
      * Converts all separators to the Windows separator of backslash.
      *
-     * @param path  the path to be changed, null ignored
+     * @param path the path to be changed, null ignored
      * @return the updated path
      * @since 2.12.0
      */

src/main/java/org/apache/commons/io/FileSystemUtils.java

@@ -212,7 +212,7 @@ public static long freeSpaceKb(final String path, final long timeout) throws IOE
      * <p>
      * Identical to:
      * <pre>
-     * freeSpaceKb(new File(".").getAbsolutePath())
+     * freeSpaceKb(FileUtils.current().getAbsolutePath())
      * </pre>
      * @return the amount of free drive space on the drive or volume in kilobytes
      * @throws IllegalStateException if an error occurred in initialisation
@@ -231,7 +231,7 @@ public static long freeSpaceKb() throws IOException {
      * <p>
      * Identical to:
      * <pre>
-     * freeSpaceKb(new File(".").getAbsolutePath())
+     * freeSpaceKb(FileUtils.current().getAbsolutePath())
      * </pre>
      * @param timeout The timeout amount in milliseconds or no timeout if the value
      *  is zero or less
@@ -243,7 +243,7 @@ public static long freeSpaceKb() throws IOException {
      */
     @Deprecated
     public static long freeSpaceKb(final long timeout) throws IOException {
-        return freeSpaceKb(new File(".").getAbsolutePath(), timeout);
+        return freeSpaceKb(FileUtils.current().getAbsolutePath(), timeout);
     }
 
     /**

src/main/java/org/apache/commons/io/FileUtils.java

@@ -69,6 +69,7 @@
 import org.apache.commons.io.file.PathFilter;
 import org.apache.commons.io.file.PathUtils;
 import org.apache.commons.io.file.StandardDeleteOption;
+import org.apache.commons.io.file.attribute.FileTimes;
 import org.apache.commons.io.filefilter.FileEqualsFileFilter;
 import org.apache.commons.io.filefilter.FileFileFilter;
 import org.apache.commons.io.filefilter.IOFileFilter;
@@ -3152,7 +3153,7 @@ public static void touch(final File file) throws IOException {
         if (!file.exists()) {
             newOutputStream(file, false).close();
         }
-        PathUtils.setLastModifiedTime(file.toPath());
+        FileTimes.setLastModifiedTime(file.toPath());
     }
 
     /**

src/main/java/org/apache/commons/io/comparator/AbstractFileComparator.java

@@ -30,13 +30,13 @@
 abstract class AbstractFileComparator implements Comparator<File> {
 
     /**
-     * Sort an array of files.
+     * Sorts an array of files.
      * <p>
      * This method uses {@link Arrays#sort(Object[], Comparator)} and returns the original array.
      * </p>
      *
-     * @param files The files to sort, may be null
-     * @return The sorted array
+     * @param files The files to sort, may be null.
+     * @return The sorted array.
      * @since 2.0
      */
     public File[] sort(final File... files) {
@@ -47,13 +47,13 @@ public File[] sort(final File... files) {
     }
 
     /**
-     * Sort a List of files.
+     * Sorts a List of files.
      * <p>
      * This method uses {@link Collections#sort(List, Comparator)} and returns the original list.
      * </p>
      *
-     * @param files The files to sort, may be null
-     * @return The sorted list
+     * @param files The files to sort, may be null.
+     * @return The sorted list.
      * @since 2.0
      */
     public List<File> sort(final List<File> files) {
@@ -66,7 +66,7 @@ public List<File> sort(final List<File> files) {
     /**
      * String representation of this file comparator.
      *
-     * @return String representation of this file comparator
+     * @return String representation of this file comparator.
      */
     @Override
     public String toString() {

src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java

@@ -45,33 +45,33 @@ public class CompositeFileComparator extends AbstractFileComparator implements S
 
     private static final Comparator<?>[] EMPTY_COMPARATOR_ARRAY = {};
     private static final long serialVersionUID = -2224170307287243428L;
-    private static final Comparator<?>[] NO_COMPARATORS = {};
+
     private final Comparator<File>[] delegates;
 
     /**
-     * Create a composite comparator for the set of delegate comparators.
+     * Constructs a composite comparator for the set of delegate comparators.
      *
      * @param delegates The delegate file comparators
      */
     @SuppressWarnings("unchecked") // casts 1 & 2 must be OK because types are already correct
     public CompositeFileComparator(final Comparator<File>... delegates) {
         if (delegates == null) {
-            this.delegates = (Comparator<File>[]) NO_COMPARATORS;//1
+            this.delegates = (Comparator<File>[]) EMPTY_COMPARATOR_ARRAY;//1
         } else {
             this.delegates = (Comparator<File>[]) new Comparator<?>[delegates.length];//2
             System.arraycopy(delegates, 0, this.delegates, 0, delegates.length);
         }
     }
 
     /**
-     * Create a composite comparator for the set of delegate comparators.
+     * Constructs a composite comparator for the set of delegate comparators.
      *
      * @param delegates The delegate file comparators
      */
     @SuppressWarnings("unchecked") // casts 1 & 2 must be OK because types are already correct
     public CompositeFileComparator(final Iterable<Comparator<File>> delegates) {
         if (delegates == null) {
-            this.delegates = (Comparator<File>[]) NO_COMPARATORS; //1
+            this.delegates = (Comparator<File>[]) EMPTY_COMPARATOR_ARRAY; //1
         } else {
             final List<Comparator<File>> list = new ArrayList<>();
             for (final Comparator<File> comparator : delegates) {
@@ -82,7 +82,7 @@ public CompositeFileComparator(final Iterable<Comparator<File>> delegates) {
     }
 
     /**
-     * Compare the two files using delegate comparators.
+     * Compares the two files using delegate comparators.
      *
      * @param file1 The first file to compare
      * @param file2 The second file to compare

src/main/java/org/apache/commons/io/comparator/DefaultFileComparator.java

@@ -21,7 +21,7 @@
 import java.util.Comparator;
 
 /**
- * Compare two files using the <b>default</b> {@link File#compareTo(File)} method.
+ * s two files using the <b>default</b> {@link File#compareTo(File)} method.
  * <p>
  * This comparator can be used to sort lists or arrays of files
  * by using the default file comparison.
@@ -56,7 +56,7 @@ public class DefaultFileComparator extends AbstractFileComparator implements Ser
     public static final Comparator<File> DEFAULT_REVERSE = new ReverseFileComparator(DEFAULT_COMPARATOR);
 
     /**
-     * Compare the two files using the {@link File#compareTo(File)} method.
+     * Compares the two files using the {@link File#compareTo(File)} method.
      *
      * @param file1 The first file to compare
      * @param file2 The second file to compare

src/main/java/org/apache/commons/io/comparator/DirectoryFileComparator.java

@@ -26,17 +26,18 @@
  * This comparator can be used to sort lists or arrays by directories and files.
  * </p>
  * <p>
- * Example of sorting a list of files/directories using the
- * {@link #DIRECTORY_COMPARATOR} singleton instance:
+ * Example of sorting a list of files/directories using the {@link #DIRECTORY_COMPARATOR} singleton instance:
  * </p>
+ * 
  * <pre>
  *       List&lt;File&gt; list = ...
  *       ((AbstractFileComparator) DirectoryFileComparator.DIRECTORY_COMPARATOR).sort(list);
  * </pre>
  * <p>
- * Example of doing a <i>reverse</i> sort of an array of files/directories using the
- * {@link #DIRECTORY_REVERSE} singleton instance:
+ * Example of doing a <i>reverse</i> sort of an array of files/directories using the {@link #DIRECTORY_REVERSE}
+ * singleton instance:
  * </p>
+ * 
  * <pre>
  *       File[] array = ...
  *       ((AbstractFileComparator) DirectoryFileComparator.DIRECTORY_REVERSE).sort(array);
@@ -59,23 +60,22 @@ public class DirectoryFileComparator extends AbstractFileComparator implements S
     public static final Comparator<File> DIRECTORY_REVERSE = new ReverseFileComparator(DIRECTORY_COMPARATOR);
 
     /**
-     * Compare the two files using the {@link File#isDirectory()} method.
+     * Compares the two files using the {@link File#isDirectory()} method.
      *
-     * @param file1 The first file to compare
-     * @param file2 The second file to compare
-     * @return the result of calling file1's
-     * {@link File#compareTo(File)} with file2 as the parameter.
+     * @param file1 The first file to compare.
+     * @param file2 The second file to compare.
+     * @return the result of calling file1's {@link File#compareTo(File)} with file2 as the parameter.
      */
     @Override
     public int compare(final File file1, final File file2) {
         return getType(file1) - getType(file2);
     }
 
     /**
-     * Convert type to numeric value.
+     * Converts type to numeric value.
      *
-     * @param file The file
-     * @return 1 for directories and 2 for files
+     * @param file The file.
+     * @return 1 for directories and 2 for files.
      */
     private int getType(final File file) {
         return file.isDirectory() ? TYPE_DIRECTORY : TYPE_FILE;

src/main/java/org/apache/commons/io/comparator/ExtensionFileComparator.java

@@ -80,14 +80,14 @@ public class ExtensionFileComparator extends AbstractFileComparator implements S
     private final IOCase caseSensitivity;
 
     /**
-     * Construct a case sensitive file extension comparator instance.
+     * Constructs a case sensitive file extension comparator instance.
      */
     public ExtensionFileComparator() {
         this.caseSensitivity = IOCase.SENSITIVE;
     }
 
     /**
-     * Construct a file extension comparator instance with the specified case-sensitivity.
+     * Constructs a file extension comparator instance with the specified case-sensitivity.
      *
      * @param caseSensitivity how to handle case sensitivity, null means case-sensitive
      */
@@ -96,7 +96,7 @@ public ExtensionFileComparator(final IOCase caseSensitivity) {
     }
 
     /**
-     * Compare the extensions of two files the specified case sensitivity.
+     * Compares the extensions of two files the specified case sensitivity.
      *
      * @param file1 The first file to compare
      * @param file2 The second file to compare

src/main/java/org/apache/commons/io/comparator/NameFileComparator.java

@@ -76,14 +76,14 @@ public class NameFileComparator extends AbstractFileComparator implements Serial
     private final IOCase caseSensitivity;
 
     /**
-     * Construct a case sensitive file name comparator instance.
+     * Constructs a case sensitive file name comparator instance.
      */
     public NameFileComparator() {
         this.caseSensitivity = IOCase.SENSITIVE;
     }
 
     /**
-     * Construct a file name comparator instance with the specified case-sensitivity.
+     * Constructs a file name comparator instance with the specified case-sensitivity.
      *
      * @param caseSensitivity  how to handle case sensitivity, null means case-sensitive
      */
@@ -92,7 +92,7 @@ public NameFileComparator(final IOCase caseSensitivity) {
     }
 
     /**
-     * Compare the names of two files with the specified case sensitivity.
+     * Compares the names of two files with the specified case sensitivity.
      *
      * @param file1 The first file to compare
      * @param file2 The second file to compare

src/main/java/org/apache/commons/io/comparator/PathFileComparator.java

@@ -76,14 +76,14 @@ public class PathFileComparator extends AbstractFileComparator implements Serial
     private final IOCase caseSensitivity;
 
     /**
-     * Construct a case sensitive file path comparator instance.
+     * Constructs a case sensitive file path comparator instance.
      */
     public PathFileComparator() {
         this.caseSensitivity = IOCase.SENSITIVE;
     }
 
     /**
-     * Construct a file path comparator instance with the specified case-sensitivity.
+     * Constructs a file path comparator instance with the specified case-sensitivity.
      *
      * @param caseSensitivity  how to handle case sensitivity, null means case-sensitive
      */
@@ -92,7 +92,7 @@ public PathFileComparator(final IOCase caseSensitivity) {
     }
 
     /**
-     * Compare the paths of two files the specified case sensitivity.
+     * Compares the paths of two files the specified case sensitivity.
      *
      * @param file1 The first file to compare
      * @param file2 The second file to compare