Improve documentation (#395)

* Improve documentation

Explicitly document thread-safety guarantees, PeekSource behavior and FileSystem support for JS-target.

Closes #392, #393, #394

core/Module.md

@@ -83,6 +83,10 @@ Core IO primitives.
 
 Basic API for working with files.
 
+#### Thread-safety guarantees
+
+Until stated otherwise, types and functions provided by the library are not thread safe.
+
 #### Known issues
 
 - [#312](https://github.com/Kotlin/kotlinx-io/issues/312) For `wasmWasi` target, directory listing ([kotlinx.io.files.FileSystem.list]) does not work with NodeJS runtime on Windows,

core/common/src/Buffer.kt

@@ -41,6 +41,12 @@ import kotlin.jvm.JvmSynthetic
  * [Buffer] implements both [Source] and [Sink] and could be used as a source or a sink,
  * but unlike regular sinks and sources its [close], [flush], [emit], [hintEmit]
  * does not affect buffer's state and [exhausted] only indicates that a buffer is empty.
+ *
+ * ### Thread-safety guarantees
+ *
+ * [Buffer] does not provide any thread-safety guarantees.
+ * If a [Buffer] needs to be accessed from multiple threads, an additional synchronization is required.
+ * Failure to do so will result in possible data corruption, loss, and runtime errors.
  */
 public class Buffer : Source, Sink {
     @PublishedApi

core/common/src/RawSink.kt

@@ -32,6 +32,11 @@ package kotlinx.io
  *
  * Implementors should abstain from throwing exceptions other than those that are documented for RawSink methods.
  *
+ * ### Thread-safety guarantees
+ *
+ * [RawSink] implementations are not required to be thread safe.
+ * However, if an implementation provides some thread safety guarantees, it is recommended to explicitly document them.
+ *
  * @sample kotlinx.io.samples.Crc32Sample.crc32
  */
 public expect interface RawSink : AutoCloseable {

core/common/src/RawSource.kt

@@ -32,6 +32,11 @@ package kotlinx.io
  *
  * Implementors should abstain from throwing exceptions other than those that are documented for RawSource methods.
  *
+ * ### Thread-safety guarantees
+ *
+ * [RawSource] implementations are not required to be thread safe.
+ * However, if an implementation provides some thread safety guarantees, it is recommended to explicitly document them.
+ *
  * @sample kotlinx.io.samples.RC4SourceSample.rc4
  */
 public interface RawSource : AutoCloseable {

core/common/src/Sink.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers.
+ * Copyright 2017-2024 JetBrains s.r.o. and respective authors and developers.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file.
  */
 
@@ -50,6 +50,11 @@ package kotlinx.io
  * Methods fully consuming its argument are named `transferFrom`, like [transferFrom].
  *
  * It is recommended to follow the same naming convention for Sink extensions.
+ *
+ * ### Thread-safety guarantees
+ *
+ * Until stated otherwise, [Sink] implementations are not thread safe.
+ * If a [Sink] needs to be accessed from multiple threads, an additional synchronization is required.
  */
 public sealed interface Sink : RawSink {
     /**

core/common/src/Source.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers.
+ * Copyright 2017-2024 JetBrains s.r.o. and respective authors and developers.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file.
  */
 
@@ -58,6 +58,11 @@ package kotlinx.io
  * Methods moving all data from a source to some other sink are named `transferTo`, like [transferTo].
  *
  * It is recommended to follow the same naming convention for Source extensions.
+ *
+ * ### Thread-safety guarantees
+ *
+ * Until stated otherwise, [Source] implementations are not thread safe.
+ * If a [Source] needs to be accessed from multiple threads, an additional synchronization is required.
  */
 public sealed interface Source : RawSource {
   /**
@@ -229,6 +234,12 @@ public sealed interface Source : RawSource {
    *
    * Peek could be used to lookahead and read the same data multiple times.
    *
+   * If peek source needs to access more data that this [Source] has in its buffer,
+   * more data will be requested from the underlying source and on success,
+   * it'll be added to the buffer of this [Source].
+   * If the underlying source was exhausted or some error occurred on attempt to fill the buffer,
+   * a corresponding exception will be thrown.
+   *
    * @throws IllegalStateException when the source is closed.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.peekSample

core/common/src/files/FileSystem.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file.
  */
 
@@ -21,6 +21,11 @@ import kotlinx.io.RawSource
  * access to some network resources and allow working with them as with regular files, for example.
  *
  * **This API is unstable and subject to change.**
+ *
+ * ### Thread-safety guarantees
+ *
+ * Until stated otherwise, [FileSystem] implementation are not thread safe.
+ * If a [FileSystem] needs to be accessed from multiple threads, an additional synchronization is required.
  */
 public sealed interface FileSystem {
     /**
@@ -170,6 +175,9 @@ internal abstract class SystemFileSystemImpl : FileSystem
 
 /**
  * An instance of [FileSystem] representing a default system-wide filesystem.
+ *
+ * *For `js` target, `SystemFileSystem` is only supported in `nodeJs` environment. Attempts to use it in `browser`
+ * environment will result in runtime exception being thrown.*
  */
 public expect val SystemFileSystem: FileSystem