IO-215 Improve documentation regarding preserving the last modified date

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@995431 13f79535-47bb-0310-9956-ffa450edef68

Author: Niall Pemberton

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

@@ -603,6 +603,10 @@ public static URL[] toURLs(File[] files) throws IOException {
      * to a file of the same name in the specified destination directory.
      * The destination directory is created if it does not exist.
      * If the destination file exists, then this method will overwrite it.
+     * <p>
+     * <strong>Note:</strong> This method tries to preserve the file's last
+     * modified date/times using {@link File#setLastModified(long)}, however
+     * it is not guaranteed that the operation will succeed.
      *
      * @param srcFile  an existing file to copy, must not be <code>null</code>
      * @param destDir  the directory to place the copy in, must not be <code>null</code>
@@ -623,6 +627,11 @@ public static void copyFileToDirectory(File srcFile, File destDir) throws IOExce
      * to a file of the same name in the specified destination directory.
      * The destination directory is created if it does not exist.
      * If the destination file exists, then this method will overwrite it.
+     * <p>
+     * <strong>Note:</strong> Setting <code>preserveFileDate</code> to
+     * <code>true</code> tries to preserve the file's last modified
+     * date/times using {@link File#setLastModified(long)}, however it is
+     * not guaranteed that the operation will succeed.
      *
      * @param srcFile  an existing file to copy, must not be <code>null</code>
      * @param destDir  the directory to place the copy in, must not be <code>null</code>
@@ -653,6 +662,10 @@ public static void copyFileToDirectory(File srcFile, File destDir, boolean prese
      * specified destination file. The directory holding the destination file is
      * created if it does not exist. If the destination file exists, then this
      * method will overwrite it.
+     * <p>
+     * <strong>Note:</strong> This method tries to preserve the file's last
+     * modified date/times using {@link File#setLastModified(long)}, however
+     * it is not guaranteed that the operation will succeed.
      * 
      * @param srcFile  an existing file to copy, must not be <code>null</code>
      * @param destFile  the new file, must not be <code>null</code>
@@ -673,6 +686,11 @@ public static void copyFile(File srcFile, File destFile) throws IOException {
      * to the specified destination file.
      * The directory holding the destination file is created if it does not exist.
      * If the destination file exists, then this method will overwrite it.
+     * <p>
+     * <strong>Note:</strong> Setting <code>preserveFileDate</code> to
+     * <code>true</code> tries to preserve the file's last modified
+     * date/times using {@link File#setLastModified(long)}, however it is
+     * not guaranteed that the operation will succeed.
      *
      * @param srcFile  an existing file to copy, must not be <code>null</code>
      * @param destFile  the new file, must not be <code>null</code>
@@ -767,6 +785,10 @@ private static void doCopyFile(File srcFile, File destFile, boolean preserveFile
      * The destination directory is created if it does not exist.
      * If the destination directory did exist, then this method merges
      * the source with the destination, with the source taking precedence.
+     * <p>
+     * <strong>Note:</strong> This method tries to preserve the files' last
+     * modified date/times using {@link File#setLastModified(long)}, however
+     * it is not guaranteed that those operations will succeed.
      *
      * @param srcDir  an existing directory to copy, must not be <code>null</code>
      * @param destDir  the directory to place the copy in, must not be <code>null</code>
@@ -802,6 +824,10 @@ public static void copyDirectoryToDirectory(File srcDir, File destDir) throws IO
      * The destination directory is created if it does not exist.
      * If the destination directory did exist, then this method merges
      * the source with the destination, with the source taking precedence.
+     * <p>
+     * <strong>Note:</strong> This method tries to preserve the files' last
+     * modified date/times using {@link File#setLastModified(long)}, however
+     * it is not guaranteed that those operations will succeed.
      *
      * @param srcDir  an existing directory to copy, must not be <code>null</code>
      * @param destDir  the new directory, must not be <code>null</code>
@@ -824,6 +850,11 @@ public static void copyDirectory(File srcDir, File destDir) throws IOException {
      * The destination directory is created if it does not exist.
      * If the destination directory did exist, then this method merges
      * the source with the destination, with the source taking precedence.
+     * <p>
+     * <strong>Note:</strong> Setting <code>preserveFileDate</code> to
+     * <code>true</code> tries to preserve the files' last modified
+     * date/times using {@link File#setLastModified(long)}, however it is
+     * not guaranteed that those operations will succeed.
      *
      * @param srcDir  an existing directory to copy, must not be <code>null</code>
      * @param destDir  the new directory, must not be <code>null</code>
@@ -849,6 +880,10 @@ public static void copyDirectory(File srcDir, File destDir,
      * The destination directory is created if it does not exist.
      * If the destination directory did exist, then this method merges
      * the source with the destination, with the source taking precedence.
+     * <p>
+     * <strong>Note:</strong> This method tries to preserve the files' last
+     * modified date/times using {@link File#setLastModified(long)}, however
+     * it is not guaranteed that those operations will succeed.
      *
      * <h4>Example: Copy directories only</h4> 
      *  <pre>
@@ -893,6 +928,11 @@ public static void copyDirectory(File srcDir, File destDir,
      * The destination directory is created if it does not exist.
      * If the destination directory did exist, then this method merges
      * the source with the destination, with the source taking precedence.
+     * <p>
+     * <strong>Note:</strong> Setting <code>preserveFileDate</code> to
+     * <code>true</code> tries to preserve the files' last modified
+     * date/times using {@link File#setLastModified(long)}, however it is
+     * not guaranteed that those operations will succeed.
      *
      * <h4>Example: Copy directories only</h4> 
      *  <pre>