Fixed/clarified KDoc and added/fixed related tests

Author: fzhinkin

core/common/src/-CommonPlatform.kt

@@ -23,10 +23,16 @@ package kotlinx.io
 
 internal expect fun String.asUtf8ToByteArray(): ByteArray
 
+/**
+ * Signals about a general issue occurred during I/O operation.
+ */
 public expect open class IOException(message: String?, cause: Throwable?) : Exception {
     public constructor(message: String? = null)
 }
 
+/**
+ * Signals that the end of the file or stream was reached unexpectedly during an input operation.
+ */
 public expect open class EOFException(message: String? = null) : IOException
 
 
@@ -35,4 +41,4 @@ public expect open class EOFException(message: String? = null) : IOException
 // This is a workaround that should be removed as soon as stdlib will support AutoCloseable
 // actual typealias on JVM.
 @OptIn(ExperimentalStdlibApi::class)
-internal typealias AutoCloseableAlias = AutoCloseable
+internal typealias AutoCloseableAlias = AutoCloseable

core/common/src/files/FileSystem.kt

@@ -10,7 +10,7 @@ import kotlinx.io.Sink
 import kotlinx.io.Source
 
 /**
- * An interface providing basic operations on a file system.
+ * An interface providing basic operations on a filesystem.
  *
  * **This API is unstable and subject to change.**
  */
@@ -21,7 +21,7 @@ public sealed interface FileSystem {
     public val temporaryDirectory: Path
 
     /**
-     * Returns `true` if there is a file system entity corresponding to a [path],
+     * Returns `true` if there is a filesystem entity a [path] points to,
      * otherwise returns `false`.
      *
      * @param path the path that should be checked for existence.
@@ -31,15 +31,18 @@ public sealed interface FileSystem {
     public fun exists(path: Path): Boolean
 
     /**
-     * Deletes [path] from a file system. If there is no file system entity
-     * represented by the [path] this method throws [kotlinx.io.files.FileNotFoundException] when [mustExist]
-     * is `true`.
+     * Deletes a file or directory the [path] points to from a filesystem.
+     * If there is no filesystem entity represented by the [path]
+     * this method throws [kotlinx.io.files.FileNotFoundException] when [mustExist] is `true`.
      *
-     * @param path the path to be deleted.
+     * Note that in the case of a directory, this method will not attempt to delete it recursively,
+     * so deletion of non-empty directory will fail.
+     *
+     * @param path the path to a file or directory to be deleted.
      * @param mustExist the flag indicating whether missing [path] is an error, `true` by default.
      *
      * @throws kotlinx.io.files.FileNotFoundException when [path] does not exist and [mustExist] is `true`.
-     * @throws kotlinx.io.IOException if the [path] could not be deleted.
+     * @throws kotlinx.io.IOException if deletion failed.
      */
     public fun delete(path: Path, mustExist: Boolean = true)
 
@@ -48,7 +51,7 @@ public sealed interface FileSystem {
      * If [path] already exists then the method throws [kotlinx.io.IOException] when [mustCreate] is `true`.
      * The call will attempt to create only missing directories.
      * The method is not atomic and if it fails after creating some
-     * directories these directories will not be deleted automatically.
+     * directories, these directories will not be deleted automatically.
      * Permissions for created directories are platform-specific.
      *
      * @param path the path to be created.
@@ -63,26 +66,28 @@ public sealed interface FileSystem {
     /**
      * Atomically renames [source] to [destination] overriding [destination] if it already exists.
      *
-     * When the file system does not support atomic move of [source] and [destination] corresponds to different
-     * file systems and the operation could not be performed atomically,
+     * When the filesystem does not support atomic move of [source] and [destination] corresponds to different
+     * filesystems and the operation could not be performed atomically,
      * [UnsupportedOperationException] is thrown.
      *
      * @param source the path to rename.
      * @param destination desired path name.
      *
      * @throws kotlinx.io.files.FileNotFoundException when the [source] does not exist.
      * @throws kotlinx.io.IOException when the move failed.
-     * @throws kotlin.UnsupportedOperationException when the file system does not support atomic move.
+     * @throws kotlin.UnsupportedOperationException when the filesystem does not support atomic move.
      */
     public fun atomicMove(source: Path, destination: Path)
 
     /**
-     * Returns [Source] to read from a file represented by the [path].
+     * Returns [Source] to read from a file the [path] points to.
      *
      * How a source will read the data is implementation-specific and failures caused
      * by the missing file or, for example, lack of permissions may not be reported immediately,
      * but postponed until the source will try to fetch data.
      *
+     * If [path] points to a directory, this method will fail with [IOException].
+     *
      * @param path the path to read from.
      *
      * @throws kotlinx.io.files.FileNotFoundException when the file does not exist.
@@ -91,19 +96,21 @@ public sealed interface FileSystem {
     public fun read(path: Path): Source
 
     /**
-     * Returns [Sink] to write into a file represented by the [path].
+     * Returns [Sink] to write into a file the [path] points to.
      * File will be created if it does not exist yet.
      *
      * How a sink will write the data is implementation-specific and failures caused,
      * for example, by the lack of permissions may not be reported immediately,
      * but postponed until the sink will try to store data.
      *
+     * If [path] points to a directory, this method will fail with [IOException].
+     *
      * @throws kotlinx.io.IOException when it's not possible to open the file for writing.
      */
     public fun write(path: Path): Sink
 
     /**
-     * Return [FileMetadata] associated with a file or directory represented by the [path].
+     * Return [FileMetadata] associated with a file or directory the [path] points to.
      * If there is no such file or directory, or it's impossible to fetch metadata,
      * `null` is returned.
      *
@@ -113,7 +120,7 @@ public sealed interface FileSystem {
 
     public companion object {
         /**
-         * An instance of [FileSystem] representing a default system-wide file system.
+         * An instance of [FileSystem] representing a default system-wide filesystem.
          */
         public val System: FileSystem = SystemFileSystem
     }
@@ -129,6 +136,9 @@ internal abstract class SystemFileSystemImpl : FileSystem {
 
 internal expect val SystemFileSystem: FileSystem
 
+/**
+ * Represents information about a file or directory obtainable from a filesystem.
+ */
 public class FileMetadata(
     /**
      * Flag indicating that the metadata was retrieved for a regular file.
@@ -144,4 +154,7 @@ public class FileMetadata(
     public val size: Long = 0L
 )
 
+/**
+ * Signals an I/O operation's failure due to a missing file or directory.
+ */
 public expect class FileNotFoundException(message: String?) : IOException

core/common/test/files/SmokeFileTest.kt

@@ -263,6 +263,39 @@ class SmokeFileTest {
         assertNotEquals(p0, Path(p0, "d", ".."))
     }
 
+    @Test
+    fun deleteNonEmptyDirectory() {
+        val basePath = createTempPath()
+        val childPath = Path(basePath, "child")
+
+        FileSystem.System.createDirectories(childPath, true)
+        assertFailsWith<IOException> { FileSystem.System.delete(basePath) }
+
+        FileSystem.System.delete(childPath)
+        FileSystem.System.delete(basePath)
+    }
+
+    @Test
+    fun readDirectory() {
+        val dir = createTempPath()
+        FileSystem.System.createDirectories(dir)
+
+        assertFailsWith<IOException> { FileSystem.System.read(dir).readByte() }
+    }
+
+    @OptIn(ExperimentalStdlibApi::class)
+    @Test
+    fun writeDirectory() {
+        val dir = createTempPath()
+        FileSystem.System.createDirectories(dir)
+
+        assertFailsWith<IOException> {
+            FileSystem.System.write(dir).use {
+                it.writeByte(0)
+            }
+        }
+    }
+
     private fun constructAbsolutePath(vararg parts: String): String {
         return Path.separator.toString() + parts.joinToString(Path.separator.toString())
     }

core/js/src/files/PathsJs.kt

@@ -155,11 +155,15 @@ private class FileSink(private val path: Path) : RawSink {
             val segmentBytes = head.limit - head.pos
             val buf = buffer.Buffer.allocUnsafe(segmentBytes)
             buf.fill(head.data, head.pos, segmentBytes)
-            if (append) {
-                fs.appendFileSync(path.toString(), buf)
-            } else {
-                fs.writeFileSync(path.toString(), buf)
-                append = true
+            try {
+                if (append) {
+                    fs.appendFileSync(path.toString(), buf)
+                } else {
+                    fs.writeFileSync(path.toString(), buf)
+                    append = true
+                }
+            } catch (e: Throwable) {
+                throw IOException("Write failed", e)
             }
 
             source.skip(segmentBytes.toLong())