From e9ccc480b09dfd672122603a79f9c0da56876171 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Wed, 13 Jul 2016 19:38:37 +0300
Subject: [PATCH] Docs: improve docs for Closeable.use and AutoCloseable.use

---
 libraries/stdlib/jre7/src/kotlin/Standard.kt | 10 ++++++++++
 libraries/stdlib/src/kotlin/io/ReadWrite.kt  |  5 ++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/libraries/stdlib/jre7/src/kotlin/Standard.kt b/libraries/stdlib/jre7/src/kotlin/Standard.kt
index 00f23986da896..68ff07c1c112a 100644
--- 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
index 3f74f10db6cb6..88f43f37a5326 100644
--- 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 {