Updated public API KDoc with information of possible IOException throwing (#351)

Author: fzhinkin

core/common/src/ByteStrings.kt

@@ -21,6 +21,7 @@ import kotlin.math.min
  * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of [byteString] indices.
  * @throws IllegalArgumentException when `startIndex > endIndex`.
  * @throws IllegalStateException if the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.ByteStringSamples.writeByteString
  */
@@ -56,6 +57,7 @@ public fun Sink.write(byteString: ByteString, startIndex: Int = 0, endIndex: Int
  * Consumes all bytes from this source and wraps it into a byte string.
  *
  * @throws IllegalStateException if the source is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.ByteStringSamples.readByteString
  */
@@ -72,6 +74,7 @@ public fun Source.readByteString(): ByteString {
  * @throws EOFException when the source is exhausted before reading [byteCount] bytes from it.
  * @throws IllegalArgumentException when [byteCount] is negative.
  * @throws IllegalStateException if the source is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.ByteStringSamples.readByteString
  */
@@ -90,6 +93,7 @@ public fun Source.readByteString(byteCount: Int): ByteString {
  *
  * @throws IllegalArgumentException if [startIndex] is negative.
  * @throws IllegalStateException if the source is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.ByteStringSamples.indexOfByteString
  */

core/common/src/RawSink.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.
  */
 
@@ -43,19 +43,23 @@ public expect interface RawSink : AutoCloseable {
      *
      * @throws IllegalArgumentException when the [source]'s size is below [byteCount] or [byteCount] is negative.
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      */
     public fun write(source: Buffer, byteCount: Long)
 
     /**
      * Pushes all buffered bytes to their final destination.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      */
     public fun flush()
 
     /**
      * Pushes all buffered bytes to their final destination and releases the resources held by this
      * sink. It is an error to write a closed sink. It is safe to close a sink more than once.
+     *
+     * @throws IOException when some I/O error occurs.
      */
     override fun close()
 }

core/common/src/RawSource.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.
  */
 
@@ -44,6 +44,7 @@ public interface RawSource : AutoCloseable {
      *
      * @throws IllegalArgumentException when [byteCount] is negative.
      * @throws IllegalStateException when the source is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readAtMostToSink
      */
@@ -52,6 +53,8 @@ public interface RawSource : AutoCloseable {
     /**
      * Closes this source and releases the resources held by this source. It is an error to read a
      * closed source. It is safe to close a source more than once.
+     *
+     * @throws IOException when some I/O error occurs.
      */
     override fun close()
 }

core/common/src/Sink.kt

@@ -76,6 +76,7 @@ public sealed interface Sink : RawSink {
      * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of [source] array indices.
      * @throws IllegalArgumentException when `startIndex > endIndex`.
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeByteArrayToSink
      */
@@ -88,6 +89,7 @@ public sealed interface Sink : RawSink {
      * @param source the source to consume data from.
      *
      * @throws IllegalStateException when the sink or [source] is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.transferFrom
      */
@@ -104,6 +106,7 @@ public sealed interface Sink : RawSink {
      *
      * @throws IllegalArgumentException when [byteCount] is negative.
      * @throws IllegalStateException when the sink or [source] is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeSourceToSink
      */
@@ -115,6 +118,7 @@ public sealed interface Sink : RawSink {
      * @param byte the byte to be written.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeByte
      */
@@ -126,6 +130,7 @@ public sealed interface Sink : RawSink {
      * @param short the short integer to be written.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeShort
      */
@@ -137,6 +142,7 @@ public sealed interface Sink : RawSink {
      * @param int the integer to be written.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeInt
      */
@@ -148,6 +154,7 @@ public sealed interface Sink : RawSink {
      * @param long the long integer to be written.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeLong
      */
@@ -158,6 +165,7 @@ public sealed interface Sink : RawSink {
      * Then the underlying sink is explicitly flushed.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.flush
      */
@@ -171,6 +179,7 @@ public sealed interface Sink : RawSink {
      * Call this method before a buffered sink goes out of scope so that its data can reach its destination.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      *
      * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.emit
      */
@@ -189,6 +198,7 @@ public sealed interface Sink : RawSink {
      * Consider using [Sink.writeToInternalBuffer] for writes into [buffered] followed by [hintEmit] call.
      *
      * @throws IllegalStateException when the sink is closed.
+     * @throws IOException when some I/O error occurs.
      */
     @InternalIoApi
     public fun hintEmit()

core/common/src/Sinks.kt

@@ -19,6 +19,7 @@ private val HEX_DIGIT_BYTES = ByteArray(16) {
  * @param short the short integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeShortLe
  */
@@ -32,6 +33,7 @@ public fun Sink.writeShortLe(short: Short) {
  * @param int the integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeIntLe
  */
@@ -45,6 +47,7 @@ public fun Sink.writeIntLe(int: Int) {
  * @param long the long integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeLongLe
  */
@@ -60,6 +63,7 @@ public fun Sink.writeLongLe(long: Long) {
  * @param long the long to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeDecimalLong
  */
@@ -141,6 +145,7 @@ public fun Sink.writeDecimalLong(long: Long) {
  * @param long the long to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeHexLong
  */
@@ -176,6 +181,7 @@ public fun Sink.writeHexadecimalUnsignedLong(long: Long) {
  * @param byte the byte to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeUByte
  */
@@ -189,6 +195,7 @@ public fun Sink.writeUByte(byte: UByte) {
  * @param short the unsigned short integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeUShort
  */
@@ -202,6 +209,7 @@ public fun Sink.writeUShort(short: UShort) {
  * @param int the unsigned integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeUInt
  */
@@ -215,6 +223,7 @@ public fun Sink.writeUInt(int: UInt) {
  * @param long the unsigned long integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeULong
  */
@@ -228,6 +237,7 @@ public fun Sink.writeULong(long: ULong) {
  * @param short the unsigned short integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeUShortLe
  */
@@ -241,6 +251,7 @@ public fun Sink.writeUShortLe(short: UShort) {
  * @param int the unsigned integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeUIntLe
  */
@@ -254,6 +265,7 @@ public fun Sink.writeUIntLe(int: UInt) {
  * @param long the unsigned long integer to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeULongLe
  */
@@ -276,6 +288,7 @@ public fun Sink.writeULongLe(long: ULong) {
  * @param float the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeFloat
  */
@@ -294,6 +307,7 @@ public fun Sink.writeFloat(float: Float) {
  * @param double the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeDouble
  */
@@ -316,6 +330,7 @@ public fun Sink.writeDouble(double: Double) {
  * @param float the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeFloatLe
  */
@@ -334,6 +349,7 @@ public fun Sink.writeFloatLe(float: Float) {
  * @param double the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  *
  * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.writeDoubleLe
  */
@@ -353,6 +369,7 @@ public fun Sink.writeDoubleLe(double: Double) {
  * @param lambda the callback accessing internal buffer.
  *
  * @throws IllegalStateException when the sink is closed.
+ * @throws IOException when some I/O error occurs.
  */
 @DelicateIoApi
 @OptIn(InternalIoApi::class, ExperimentalContracts::class)

core/common/src/Source.kt

@@ -77,6 +77,7 @@ public sealed interface Source : RawSource {
    * The call of this method will block until there are bytes to read or the source is definitely exhausted.
    *
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.exhausted
    */
@@ -94,6 +95,7 @@ public sealed interface Source : RawSource {
    * @throws EOFException when the source is exhausted before the required bytes count could be read.
    * @throws IllegalStateException when the source is closed.
    * @throws IllegalArgumentException when [byteCount] is negative.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.require
    */
@@ -110,6 +112,7 @@ public sealed interface Source : RawSource {
    *
    * @throws IllegalArgumentException when [byteCount] is negative.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.request
    */
@@ -120,6 +123,7 @@ public sealed interface Source : RawSource {
    *
    * @throws EOFException when there are no more bytes to read.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readByte
    */
@@ -130,6 +134,7 @@ public sealed interface Source : RawSource {
    *
    * @throws EOFException when there are not enough data to read a short value.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readShort
    */
@@ -140,6 +145,7 @@ public sealed interface Source : RawSource {
    *
    * @throws EOFException when there are not enough data to read an int value.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readInt
    */
@@ -150,6 +156,7 @@ public sealed interface Source : RawSource {
    *
    * @throws EOFException when there are not enough data to read a long value.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readLong
    */
@@ -163,6 +170,7 @@ public sealed interface Source : RawSource {
    * @throws EOFException when the source is exhausted before the requested number of bytes can be skipped.
    * @throws IllegalArgumentException when [byteCount] is negative.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.skip
    */
@@ -179,6 +187,7 @@ public sealed interface Source : RawSource {
    * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of [sink] array indices.
    * @throws IllegalArgumentException when `startIndex > endIndex`.
    * @throws IllegalStateException when the source is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readAtMostToByteArray
    */
@@ -193,6 +202,7 @@ public sealed interface Source : RawSource {
    * @throws IllegalArgumentException when [byteCount] is negative.
    * @throws EOFException when the requested number of bytes cannot be read.
    * @throws IllegalStateException when the source or [sink] is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.readSourceToSink
    */
@@ -207,6 +217,7 @@ public sealed interface Source : RawSource {
    * @param sink the sink to which data will be written from this source.
    *
    * @throws IllegalStateException when the source or [sink] is closed.
+   * @throws IOException when some I/O error occurs.
    *
    * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.transferTo
    */