doc review

libraries/stdlib/src/kotlin/collections/JUtil.kt

@@ -51,20 +51,20 @@ public fun setOf<T>(vararg values: T): Set<T> = if (values.size() == 0) emptySet
 /** Returns an empty read-only set. */
 public fun setOf<T>(): Set<T> = emptySet()
 
-/** Returns a new LinkedList with the given elements. */
+/** Returns a new [LinkedList] with the given elements. */
 public fun linkedListOf<T>(vararg values: T): LinkedList<T> = values.toCollection(LinkedList<T>())
 
-/** Returns a new ArrayList with the given elements. */
+/** Returns a new [ArrayList] with the given elements. */
 public fun arrayListOf<T>(vararg values: T): ArrayList<T> = values.toCollection(ArrayList(values.size()))
 
-/** Returns a new HashSet with the given elements. */
+/** Returns a new [HashSet] with the given elements. */
 public fun hashSetOf<T>(vararg values: T): HashSet<T> = values.toCollection(HashSet(values.size()))
 
-/** Returns a new LinkedHashSet with the given elements. */
+/** Returns a new [LinkedHashSet] with the given elements. */
 public fun linkedSetOf<T>(vararg values: T): LinkedHashSet<T> = 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

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 <T> Lock.withLock(action: () -> T): T {
     lock()
@@ -18,8 +18,8 @@ public inline fun <T> 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 <T> ReentrantReadWriteLock.read(action: () -> T): T {
     val rl = readLock()
@@ -32,10 +32,10 @@ public inline fun <T> 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 <T> ReentrantReadWriteLock.write(action: () -> T): T {
     val rl = readLock()
@@ -54,8 +54,8 @@ public inline fun <T> 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 <T> Int.latch(operation: CountDownLatch.() -> T): T {
     val latch = CountDownLatch(this)

libraries/stdlib/src/kotlin/io/ReadWrite.kt

@@ -140,11 +140,11 @@ public fun File.readLines(charset: Charset = Charsets.UTF_8): List<String> {
     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)
 

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

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)