Docs: improve docs for Closeable.use and AutoCloseable.use

JetBrains · Jul 13, 2016 · e9ccc48 · e9ccc48
1 parent b09fc7c
commit e9ccc48
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 3 deletions.
diff --git a/libraries/stdlib/jre7/src/kotlin/Standard.kt b/libraries/stdlib/jre7/src/kotlin/Standard.kt
@@ -1,6 +1,16 @@
 @file:JvmName("StandardJRE7Kt")
 package kotlin
 
+/**
+ * Executes the given [block] function on this resource and then closes it down correctly whether an exception
+ * is thrown or not.
+ *
+ * In case if the resource is being closed due to an exception occurred in [block], and the closing also fails with an exception,
+ * the latter is added to the [suppressed][java.lang.Throwable.addSuppressed] exceptions of the former.
+ *
+ * @param block a function to process this [AutoCloseable] resource.
+ * @return the result of [block] function invoked on this resource.
+ */
 @Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
 @kotlin.internal.InlineOnly
 public inline fun <T : AutoCloseable?, R> T.use(block: (T) -> R): R {

diff --git a/libraries/stdlib/src/kotlin/io/ReadWrite.kt b/libraries/stdlib/src/kotlin/io/ReadWrite.kt
@@ -143,13 +143,12 @@ public inline fun URL.readText(charset: Charset = Charsets.UTF_8): String = read
  */
 public fun URL.readBytes(): ByteArray = openStream().use { it.readBytes() }
 
-// TODO: Provide use kotlin package for AutoCloseable
 /**
  * Executes the given [block] function on this resource and then closes it down correctly whether an exception
  * is thrown or not.
  *
- * @param block a function to process this closable resource.
- * @return the result of [block] function on this closable resource.
+ * @param block a function to process this [Closeable] resource.
+ * @return the result of [block] function invoked on this resource.
  */
 @kotlin.internal.InlineOnly
 public inline fun <T : Closeable?, R> T.use(block: (T) -> R): R {