From 59dc0f57fc03e0fdec39008d98f5587bdfbf8a6e Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Wed, 12 Apr 2017 23:50:23 +0300
Subject: [PATCH] Clarify copyRecursively behavior in case of a single file.

---
 libraries/stdlib/src/kotlin/io/files/Utils.kt | 23 ++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/io/files/Utils.kt b/libraries/stdlib/src/kotlin/io/files/Utils.kt
index 1870dc8ce7a..08db97325a6 100644
--- a/libraries/stdlib/src/kotlin/io/files/Utils.kt
+++ b/libraries/stdlib/src/kotlin/io/files/Utils.kt
@@ -165,6 +165,8 @@ private fun File.toRelativeStringOrNull(base: File): String? {
  * If this file is a directory, it is copied without its content, i.e. an empty [target] directory is created.
  * If you want to copy directory including its contents, use [copyRecursively].
  *
+ * The operation doesn't preserve copied file attributes such as creation/modification date, permissions, etc.
+ *
  * @param overwrite `true` if destination overwrite is allowed.
  * @param bufferSize the buffer size to use when copying.
  * @return the [target] file.
@@ -222,20 +224,29 @@ private class TerminateException(file: File) : FileSystemException(file) {}
  * Copies this file with all its children to the specified destination [target] path.
  * If some directories on the way to the destination are missing, then they will be created.
  *
+ * If this file path points to a single file, then it will be copied to a file with the path [target].
+ * If this file path points to a directory, then its children will be copied to a directory with the path [target].
+ *
+ * If the [target] already exists, it will be deleted before copying when the [overwrite] parameter permits so.
+ *
+ * The operation doesn't preserve copied file attributes such as creation/modification date, permissions, etc.
+ *
  * If any errors occur during the copying, then further actions will depend on the result of the call
  * to `onError(File, IOException)` function, that will be called with arguments,
  * specifying the file that caused the error and the exception itself.
  * By default this function rethrows exceptions.
+ *
  * Exceptions that can be passed to the `onError` function:
- * NoSuchFileException - if there was an attempt to copy a non-existent file
- * FileAlreadyExistsException - if there is a conflict
- * AccessDeniedException - if there was an attempt to open a directory that didn't succeed.
- * IOException - if some problems occur when copying.
+ *
+ * - [NoSuchFileException] - if there was an attempt to copy a non-existent file
+ * - [FileAlreadyExistsException] - if there is a conflict
+ * - [AccessDeniedException] - if there was an attempt to open a directory that didn't succeed.
+ * - [IOException] - if some problems occur when copying.
+ *
+ * Note that if this function fails, then partial copying may have taken place.
  *
  * @param overwrite `true` if it is allowed to overwrite existing destination files and directories.
  * @return `false` if the copying was terminated, `true` otherwise.
-*
-* Note that if this function fails, then partial copying may have taken place.
  */
 public fun File.copyRecursively(target: File,
                                 overwrite: Boolean = false,