diff --git a/libraries/stdlib/src/kotlin/collections/JUtil.kt b/libraries/stdlib/src/kotlin/collections/JUtil.kt index 5f5cabe946f..5f4d861431f 100644 --- a/libraries/stdlib/src/kotlin/collections/JUtil.kt +++ b/libraries/stdlib/src/kotlin/collections/JUtil.kt @@ -51,20 +51,20 @@ public fun setOf(vararg values: T): Set = if (values.size() == 0) emptySet /** Returns an empty read-only set. */ public fun setOf(): Set = emptySet() -/** Returns a new LinkedList with the given elements. */ +/** Returns a new [LinkedList] with the given elements. */ public fun linkedListOf(vararg values: T): LinkedList = values.toCollection(LinkedList()) -/** Returns a new ArrayList with the given elements. */ +/** Returns a new [ArrayList] with the given elements. */ public fun arrayListOf(vararg values: T): ArrayList = values.toCollection(ArrayList(values.size())) -/** Returns a new HashSet with the given elements. */ +/** Returns a new [HashSet] with the given elements. */ public fun hashSetOf(vararg values: T): HashSet = values.toCollection(HashSet(values.size())) -/** Returns a new LinkedHashSet with the given elements. */ +/** Returns a new [LinkedHashSet] with the given elements. */ public fun linkedSetOf(vararg values: T): LinkedHashSet = values.toCollection(LinkedHashSet(values.size())) /** - * Returns the valid indices for this collection. + * Returns an IntRange of the valid indices for this collection. */ public val Collection<*>.indices: IntRange get() = 0..size() - 1 diff --git a/libraries/stdlib/src/kotlin/concurrent/Locks.kt b/libraries/stdlib/src/kotlin/concurrent/Locks.kt index 095ee174cd7..6d3e6ccf03d 100644 --- a/libraries/stdlib/src/kotlin/concurrent/Locks.kt +++ b/libraries/stdlib/src/kotlin/concurrent/Locks.kt @@ -5,8 +5,8 @@ import java.util.concurrent.locks.ReentrantReadWriteLock import java.util.concurrent.CountDownLatch /** - * Executes the given calculation under this lock. - * @return result of the calculation. + * Executes the given [action] under this lock. + * @return the return value of the action. */ public inline fun Lock.withLock(action: () -> T): T { lock() @@ -18,8 +18,8 @@ public inline fun Lock.withLock(action: () -> T): T { } /** - * Executes the given calculation under the read lock of this lock. - * @return result of the calculation. + * Executes the given [action] under the read lock of this lock. + * @return the return value of the action. */ public inline fun ReentrantReadWriteLock.read(action: () -> T): T { val rl = readLock() @@ -32,10 +32,10 @@ public inline fun ReentrantReadWriteLock.read(action: () -> T): T { } /** - * Executes the given calculation under the write lock of this lock. + * Executes the given [action] under the write lock of this lock. * The method does upgrade from read to write lock if needed * If such write has been initiated by checking some condition, the condition must be rechecked inside the action to avoid possible races - * @return result of the calculation. + * @return the return value of the action. */ public inline fun ReentrantReadWriteLock.write(action: () -> T): T { val rl = readLock() @@ -54,8 +54,8 @@ public inline fun ReentrantReadWriteLock.write(action: () -> T): T { } /** - * Execute the given calculation and await for CountDownLatch - * @return result of the calculation. + * Executes the given [action] and await for CountDownLatch + * @return the return value of the action. */ public fun Int.latch(operation: CountDownLatch.() -> T): T { val latch = CountDownLatch(this) diff --git a/libraries/stdlib/src/kotlin/io/ReadWrite.kt b/libraries/stdlib/src/kotlin/io/ReadWrite.kt index dbe6eb045fb..3de5e5d4100 100644 --- a/libraries/stdlib/src/kotlin/io/ReadWrite.kt +++ b/libraries/stdlib/src/kotlin/io/ReadWrite.kt @@ -140,11 +140,11 @@ public fun File.readLines(charset: Charset = Charsets.UTF_8): List { return result } -/** Creates a buffered reader wrapping this Reader, or returns self if Reader is already buffered */ +/** Creates a buffered reader wrapping this Reader, or returns this Reader if it is already buffered. */ public fun Reader.buffered(bufferSize: Int = defaultBufferSize): BufferedReader = if (this is BufferedReader) this else BufferedReader(this, bufferSize) -/** Creates a buffered writer wrapping this Writer, or returns self if Writer is already buffered */ +/** Creates a buffered writer wrapping this Writer, or returns this Writer if it is already buffered. */ public fun Writer.buffered(bufferSize: Int = defaultBufferSize): BufferedWriter = if (this is BufferedWriter) this else BufferedWriter(this, bufferSize) diff --git a/libraries/stdlib/src/kotlin/jvm/JvmFlagAnnotations.kt b/libraries/stdlib/src/kotlin/jvm/JvmFlagAnnotations.kt index edb6dad62c5..8d09ed511bf 100644 --- a/libraries/stdlib/src/kotlin/jvm/JvmFlagAnnotations.kt +++ b/libraries/stdlib/src/kotlin/jvm/JvmFlagAnnotations.kt @@ -20,8 +20,8 @@ import java.lang.annotation.Retention import java.lang.annotation.RetentionPolicy /** - * Marks the JVM backing field of the annotated property as `volatile`, meaning that it can - * be modified asynchronously by concurrently running threads. + * Marks the JVM backing field of the annotated property as `volatile`, meaning that writes to this field + * are immediately made visible to other threads. */ Retention(RetentionPolicy.SOURCE) public annotation class volatile diff --git a/libraries/stdlib/src/kotlin/text/StringBuilderJVM.kt b/libraries/stdlib/src/kotlin/text/StringBuilderJVM.kt index 387b0f34421..13f9e97b5e3 100644 --- a/libraries/stdlib/src/kotlin/text/StringBuilderJVM.kt +++ b/libraries/stdlib/src/kotlin/text/StringBuilderJVM.kt @@ -17,44 +17,44 @@ public fun Appendable.appendln(value: Char): Appendable = append(value).append(L /** Appends a line separator to this StringBuilder. */ public fun StringBuilder.appendln(): StringBuilder = append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: StringBuffer?): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: CharSequence?): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: String?): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Any?): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: StringBuilder?): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: CharArray): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Char): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Boolean): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Int): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Short): StringBuilder = append(value.toInt()).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Byte): StringBuilder = append(value.toInt()).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Long): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Float): StringBuilder = append(value).append(LINE_SEPARATOR) -/** Appends value to this StringBuilder and line separator after it. */ +/** Appends [value] to this [StringBuilder], followed by a line separator. */ public fun StringBuilder.appendln(value: Double): StringBuilder = append(value).append(LINE_SEPARATOR)