Skip to content

Commit f8327c7

Browse files
elharoelharo
authored
tidy up API doc for copy methods (#549)
1 parent b51f384 commit f8327c7

1 file changed

Lines changed: 50 additions & 49 deletions

File tree

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

Lines changed: 50 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -488,20 +488,21 @@ public static File[] convertFileCollectionToFileArray(final Collection<File> fil
488488
}
489489

490490
/**
491-
* Copies a whole directory to a new location preserving the file dates.
491+
* Copies a whole directory to a new location, preserving the file dates.
492492
* <p>
493493
* This method copies the specified directory and all its child directories and files to the specified destination.
494-
* The destination is the new location and name of the directory.
494+
* The destination is the new location and name of the directory. That is, copying /home/bar to /tmp/bang
495+
* copies the contents of /home/bar into /tmp/bang. It does not create /tmp/bang/bar.
495496
* </p>
496497
* <p>
497-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
498+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
498499
* method merges the source with the destination, with the source taking precedence.
499500
* </p>
500501
* <p>
501-
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
502-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
503-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
504-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
502+
* <strong>Note:</strong> This method tries to preserve the file's last
503+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However it is
504+
* not guaranteed that the operation will succeed. If the modification operation fails, it falls back to
505+
* {@link File#setLastModified(long)}. If that fails, the method throws IOException.
505506
* </p>
506507
*
507508
* @param srcDir an existing directory to copy, must not be {@code null}.
@@ -522,13 +523,13 @@ public static void copyDirectory(final File srcDir, final File destDir) throws I
522523
* This method copies the contents of the specified source directory to within the specified destination directory.
523524
* </p>
524525
* <p>
525-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
526+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
526527
* method merges the source with the destination, with the source taking precedence.
527528
* </p>
528529
* <p>
529530
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the files' last
530-
* modified date/times using {@link File#setLastModified(long)}, however it is not guaranteed that those operations
531-
* will succeed. If the modification operation fails, the methods throws IOException.
531+
* modified date/times using {@link File#setLastModified(long)}. However it is not guaranteed that those operations
532+
* will succeed. If the modification operation fails, the method throws IOException.
532533
* </p>
533534
*
534535
* @param srcDir an existing directory to copy, must not be {@code null}.
@@ -551,13 +552,13 @@ public static void copyDirectory(final File srcDir, final File destDir, final bo
551552
* This method copies the contents of the specified source directory to within the specified destination directory.
552553
* </p>
553554
* <p>
554-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
555+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
555556
* method merges the source with the destination, with the source taking precedence.
556557
* </p>
557558
* <p>
558559
* <strong>Note:</strong> This method tries to preserve the files' last modified date/times using
559-
* {@link File#setLastModified(long)}, however it is not guaranteed that those operations will succeed. If the
560-
* modification operation fails, the methods throws IOException.
560+
* {@link File#setLastModified(long)}. However it is not guaranteed that those operations will succeed. If the
561+
* modification operation fails, the method throws IOException.
561562
* </p>
562563
* <b>Example: Copy directories only</b>
563564
*
@@ -600,14 +601,14 @@ public static void copyDirectory(final File srcDir, final File destDir, final Fi
600601
* This method copies the contents of the specified source directory to within the specified destination directory.
601602
* </p>
602603
* <p>
603-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
604+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
604605
* method merges the source with the destination, with the source taking precedence.
605606
* </p>
606607
* <p>
607608
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
608-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
609-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
610-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
609+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
610+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
611+
* {@link File#setLastModified(long)}. If that fails, the method throws IOException.
611612
* </p>
612613
* <b>Example: Copy directories only</b>
613614
*
@@ -650,14 +651,14 @@ public static void copyDirectory(final File srcDir, final File destDir, final Fi
650651
* This method copies the contents of the specified source directory to within the specified destination directory.
651652
* </p>
652653
* <p>
653-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
654+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
654655
* method merges the source with the destination, with the source taking precedence.
655656
* </p>
656657
* <p>
657658
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
658-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
659-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
660-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
659+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
660+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
661+
* {@link File#setLastModified(long)}. If that fails, the method throws IOException.
661662
* </p>
662663
* <b>Example: Copy directories only</b>
663664
*
@@ -720,14 +721,14 @@ public static void copyDirectory(final File srcDir, final File destDir, final Fi
720721
* destination directory.
721722
* </p>
722723
* <p>
723-
* The destination directory is created if it does not exist. If the destination directory did exist, then this
724+
* The destination directory is created if it does not exist. If the destination directory does exist, then this
724725
* method merges the source with the destination, with the source taking precedence.
725726
* </p>
726727
* <p>
727728
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
728-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
729-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
730-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
729+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
730+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
731+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
731732
* </p>
732733
*
733734
* @param sourceDir an existing directory to copy, must not be {@code null}.
@@ -753,9 +754,9 @@ public static void copyDirectoryToDirectory(final File sourceDir, final File des
753754
* </p>
754755
* <p>
755756
* <strong>Note:</strong> This method tries to preserve the file's last modified date/times using
756-
* {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is not guaranteed that the
757-
* operation will succeed. If the modification operation fails it will fallback to
758-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
757+
* {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is not guaranteed that the
758+
* operation will succeed. If the modification operation fails it falls back to
759+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
759760
* </p>
760761
*
761762
* @param srcFile an existing file to copy, must not be {@code null}.
@@ -780,9 +781,9 @@ public static void copyFile(final File srcFile, final File destFile) throws IOEx
780781
* </p>
781782
* <p>
782783
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
783-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
784-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
785-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
784+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
785+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
786+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
786787
* </p>
787788
*
788789
* @param srcFile an existing file to copy, must not be {@code null}.
@@ -807,9 +808,9 @@ public static void copyFile(final File srcFile, final File destFile, final boole
807808
* </p>
808809
* <p>
809810
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
810-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
811-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
812-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
811+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
812+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
813+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
813814
* </p>
814815
*
815816
* @param srcFile an existing file to copy, must not be {@code null}.
@@ -892,9 +893,9 @@ public static long copyFile(final File input, final OutputStream output) throws
892893
* </p>
893894
* <p>
894895
* <strong>Note:</strong> This method tries to preserve the file's last modified date/times using
895-
* {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is not guaranteed that the
896-
* operation will succeed. If the modification operation fails it will fallback to
897-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
896+
* {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is not guaranteed that the
897+
* operation will succeed. If the modification operation fails it falls back to
898+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
898899
* </p>
899900
*
900901
* @param srcFile an existing file to copy, must not be {@code null}.
@@ -917,9 +918,9 @@ public static void copyFileToDirectory(final File srcFile, final File destDir) t
917918
* </p>
918919
* <p>
919920
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
920-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
921-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
922-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
921+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
922+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
923+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
923924
* </p>
924925
*
925926
* @param sourceFile an existing file to copy, must not be {@code null}.
@@ -967,18 +968,18 @@ public static void copyInputStreamToFile(final InputStream source, final File de
967968
/**
968969
* Copies a file or directory to within another directory preserving the file dates.
969970
* <p>
970-
* This method copies the source file or directory, along all its contents, to a directory of the same name in the
971+
* This method copies the source file or directory, along with all its contents, to a directory of the same name in the
971972
* specified destination directory.
972973
* </p>
973974
* <p>
974-
* The destination directory is created if it does not exist. If the destination directory did exist, then this method
975+
* The destination directory is created if it does not exist. If the destination directory does exist, then this method
975976
* merges the source with the destination, with the source taking precedence.
976977
* </p>
977978
* <p>
978979
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
979-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
980-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
981-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
980+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
981+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
982+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
982983
* </p>
983984
*
984985
* @param sourceFile an existing file or directory to copy, must not be {@code null}.
@@ -1011,10 +1012,10 @@ public static void copyToDirectory(final File sourceFile, final File destination
10111012
* If the destination file exists, then this method will overwrite it.
10121013
* </p>
10131014
* <p>
1014-
* <strong>Note:</strong> Setting {@code preserveFileDate} to {@code true} tries to preserve the file's last
1015-
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}, however it is
1016-
* not guaranteed that the operation will succeed. If the modification operation fails it will fallback to
1017-
* {@link File#setLastModified(long)} and if that fails, the methods throws IOException.
1015+
* <strong>Note:</strong> This method tries to preserve the file's last
1016+
* modified date/times using {@link BasicFileAttributeView#setTimes(FileTime, FileTime, FileTime)}. However, it is
1017+
* not guaranteed that the operation will succeed. If the modification operation fails it falls back to
1018+
* {@link File#setLastModified(long)} and if that fails, the method throws IOException.
10181019
* </p>
10191020
*
10201021
* @param sourceIterable existing files to copy, must not be {@code null}.

0 commit comments

Comments
 (0)