From ae3c9dd9b91db981244fa883d5a53373750f5953 Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Wed, 3 Jan 2024 15:15:05 +0500 Subject: [PATCH] Improve Path.walk/delete/copyToRecursively documentation --- .../jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt | 8 ++++++++ libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt | 9 ++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt b/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt index b00bbb6ff7c..52a47cfb2db 100644 --- a/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt +++ b/libraries/stdlib/jdk7/src/kotlin/io/path/PathRecursiveFunctions.kt @@ -62,6 +62,10 @@ import java.nio.file.attribute.BasicFileAttributes * This exception is passed to [onError] for handling. * @throws IOException if any errors occur while copying. * This exception is passed to [onError] for handling. + * @throws FileSystemException if the source subtree contains an entry with an illegal name such as "." or "..". + * This exception is passed to [onError] for handling. + * @throws FileSystemLoopException if the recursive copy reaches a cycle. + * This exception is passed to [onError] for handling. * @throws SecurityException if a security manager is installed and access is not permitted to an entry in the source or target subtree. * This exception is passed to [onError] for handling. */ @@ -143,6 +147,10 @@ public fun Path.copyToRecursively( * @throws FileSystemException if [target] is an entry inside the source subtree. * @throws IOException if any errors occur while copying. * This exception is passed to [onError] for handling. + * @throws FileSystemException if the source subtree contains an entry with an illegal name such as "." or "..". + * This exception is passed to [onError] for handling. + * @throws FileSystemLoopException if the recursive copy reaches a cycle. + * This exception is passed to [onError] for handling. * @throws SecurityException if a security manager is installed and access is not permitted to an entry in the source or target subtree. * This exception is passed to [onError] for handling. */ diff --git a/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt b/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt index 00abc909806..c8d680ae1ef 100644 --- a/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt +++ b/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt @@ -1046,6 +1046,7 @@ public inline fun URI.toPath(): Path = * Returns a sequence of paths for visiting this directory and all its content. * * By default, only files are visited, in depth-first order, and symbolic links are not followed. + * If encountered, symbolic links are included in the sequence as-is, and the content of the directory they point to is not visited. * The combination of [options] overrides the default behavior. See [PathWalkOption]. * * The order in which sibling files are visited is unspecified. @@ -1054,7 +1055,13 @@ public inline fun URI.toPath(): Path = * the changes may or may not appear in the returned sequence. * * If the file located by this path does not exist, an empty sequence is returned. - * if the file located by this path is not a directory, a sequence containing only this path is returned. + * If the file located by this path is not a directory, a sequence containing only this path is returned. + * + * When iterating the returned sequence, the following exceptions could be thrown: + * * [FileSystemException] if the traversal reaches an entry with an illegal name such as "." or "..". + * * [FileSystemLoopException] if the traversal reaches a cycle. + * * [SecurityException] if a security manager is installed and the traversal reaches an entry whose access is not permitted. + * * [IOException] if any errors arise while opening a directory. */ @ExperimentalPathApi @SinceKotlin("1.7")