More standard library documentation updates.

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

@@ -6,6 +6,9 @@ import java.util.Arrays
 import kotlin.jvm.internal.Intrinsic
 
 // Array "constructor"
+/**
+ * Returns an array containing the specified elements.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun <reified T> array(vararg t : T) : Array<T> = t as Array<T>
 
 // "constructors" for primitive types array

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

@@ -34,33 +34,38 @@ private object EmptySet : Set<Any> {
     override fun toString(): String = set.toString()
 }
 
+/** Returns an empty read-only list. */
 public fun emptyList<T>(): List<T> = EmptyList as List<T>
+/** Returns an empty read-only set. */
 public fun emptySet<T>(): Set<T> = EmptySet as Set<T>
 
 /** Returns a new read-only list of given elements */
 public fun listOf<T>(vararg values: T): List<T> = if (values.size() == 0) emptyList() else arrayListOf(*values)
 
-/** Returns an empty read-only list */
+/** Returns an empty read-only list. */
 public fun listOf<T>(): List<T> = emptyList()
 
-/** Returns a new read-only ordered set of given elements */
+/** Returns a new read-only ordered set with the given elements. */
 public fun setOf<T>(vararg values: T): Set<T> = if (values.size() == 0) emptySet() else values.toCollection(LinkedHashSet<T>())
 
-/** Returns an empty read-only set */
+/** Returns an empty read-only set. */
 public fun setOf<T>(): Set<T> = emptySet()
 
-/** Returns a new LinkedList with a variable number of initial 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 a variable number of initial 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 a variable number of initial 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 a variable number of initial 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.
+ */
 public val Collection<*>.indices: IntRange
     get() = 0..size() - 1
 
@@ -70,7 +75,7 @@ public val Int.indices: IntRange
 /**
  * Returns the index of the last item in the list or -1 if the list is empty
  *
- * @includeFunctionBody ../../test/collections/ListSpecificTest.kt lastIndex
+ * @sample test.collections.ListSpecificTest.lastIndex
  */
 public val <T> List<T>.lastIndex: Int
     get() = this.size() - 1
@@ -78,13 +83,13 @@ public val <T> List<T>.lastIndex: Int
 /** Returns true if the collection is not empty */
 public fun <T> Collection<T>.isNotEmpty(): Boolean = !isEmpty()
 
-/** Returns the Collection if its not null otherwise it returns the empty list */
+/** Returns this Collection if it's not null and the empty list otherwise. */
 public fun <T> Collection<T>?.orEmpty(): Collection<T> = this ?: emptyList()
 
-/** Returns the List if its not null otherwise returns the empty list */
+/** Returns this List if it's not null and the empty list otherwise. */
 public fun <T> List<T>?.orEmpty(): List<T> = this ?: emptyList()
 
-/** Returns the List if its not null otherwise returns the empty list */
+/** Returns this Set if it's not null and the empty set otherwise. */
 public fun <T> Set<T>?.orEmpty(): Set<T> = this ?: emptySet()
 
 public fun <T> Iterable<T>.collectionSizeOrNull(): Int? = if (this is Collection<*>) size() else null

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

@@ -13,8 +13,7 @@ public fun sortedSetOf<T>(vararg values: T): TreeSet<T> = values.toCollection(Tr
 public fun sortedSetOf<T>(comparator: Comparator<T>, vararg values: T): TreeSet<T> = values.toCollection(TreeSet<T>(comparator))
 
 /**
- * Returns a list containing the elements returned by the
- * specified enumeration in the order they are returned by the
- * enumeration.
+ * Returns a list containing the elements returned by this enumeration
+ * in the order they are returned by the enumeration.
  */
 public fun <T> Enumeration<T>.toList(): List<T> = Collections.list(this)

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

@@ -81,8 +81,9 @@ public val <K, V> Map.Entry<K, V>.value: V
     get() = getValue()
 
 /**
- * Returns the key component of the map entry. This method allows to use multi-declarations when working with maps,
- * for example:
+ * Returns the key component of the map entry.
+ *
+ * This method allows to use multi-declarations when working with maps, for example:
  * ```
  * for ((key, value) in map) {
  *     // do something with the key and the value
@@ -94,8 +95,8 @@ public fun <K, V> Map.Entry<K, V>.component1(): K {
 }
 
 /**
- * Returns the value component of the map entry. This method allows to use multi-declarations when working with maps,
- * for example:
+ * Returns the value component of the map entry.
+ * This method allows to use multi-declarations when working with maps, for example:
  * ```
  * for ((key, value) in map) {
  *     // do something with the key and the value

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

@@ -6,14 +6,16 @@ import java.util.SortedMap
 import java.util.TreeMap
 import java.util.Properties
 
-/** Provides indexed write access to mutable maps */
+/**
+ * Allows to use the index operator for storing values in a mutable map.
+ */
 // this code is JVM-specific, because JS has native set function
 public fun <K, V> MutableMap<K, V>.set(key: K, value: V): V? = put(key, value)
 
 /**
  * Converts this [Map] to a [SortedMap] so iteration order will be in key order
  *
- * @includeFunctionBody ../../test/collections/MapTest.kt toSortedMap
+ * @sample test.collections.MapJVMTest.toSortedMap
  */
 public fun <K : Any, V> Map<K, V>.toSortedMap(): SortedMap<K, V> = TreeMap(this)
 
@@ -51,7 +53,7 @@ public fun <K, V> sortedMapOf(vararg values: Pair<K, V>): SortedMap<K, V> {
 /**
  * Converts this [Map] to a [Properties] object
  *
- * @includeFunctionBody ../../test/collections/MapTest.kt toProperties
+ * @sample test.collections.MapJVMTest.toProperties
  */
 public fun Map<String, String>.toProperties(): Properties {
     val answer = Properties()

libraries/stdlib/src/kotlin/concurrent/Locks.kt

@@ -5,8 +5,8 @@ import java.util.concurrent.locks.ReentrantReadWriteLock
 import java.util.concurrent.CountDownLatch
 
 /**
- * Executes given calculation under lock
- * Returns result of the calculation
+ * Executes the given calculation under this lock.
+ * @return result of the calculation.
  */
 public inline fun <T> Lock.withLock(action: () -> T): T {
     lock()
@@ -18,8 +18,8 @@ public inline fun <T> Lock.withLock(action: () -> T): T {
 }
 
 /**
- * Executes given calculation under read lock
- * Returns result of the calculation
+ * Executes the given calculation under the read lock of this lock.
+ * @return result of the calculation.
  */
 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 given calculation under write lock.
+ * Executes the given calculation 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
- * Returns result of the calculation
+ * @return result of the calculation.
  */
 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 given calculation and await for CountDownLatch
- * Returns result of the calculation
+ * Execute the given calculation and await for CountDownLatch
+ * @return result of the calculation.
  */
 public fun <T> Int.latch(operation: CountDownLatch.() -> T): T {
     val latch = CountDownLatch(this)

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

@@ -9,88 +9,88 @@ import java.io.BufferedReader
  */
 public val defaultBufferSize: Int = 64 * 1024
 
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Any?) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Int) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Long) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Byte) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Short) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Char) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Boolean) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Float) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: Double) {
     System.out.print(message)
 }
-/** Prints the given message to [[System.out]] */
+/** Prints the given message to [System.out] */
 public fun print(message: CharArray) {
     System.out.print(message)
 }
 
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Any?) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Int) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Long) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Byte) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Short) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Char) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Boolean) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Float) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: Double) {
     System.out.println(message)
 }
-/** Prints the given message and newline to [[System.out]] */
+/** Prints the given message and newline to [System.out] */
 public fun println(message: CharArray) {
     System.out.println(message)
 }
-/** Prints a newline t[[System.out]] */
+/** Prints a newline to [System.out] */
 public fun println() {
     System.out.println()
 }
@@ -136,5 +136,8 @@ private val stdin: BufferedReader = BufferedReader(InputStreamReader(object : In
     }
 }))
 
-/** Reads a line of input from [[System.in]] */
+/**
+ * Reads a line of input from [System.in]
+ * @return the line read or null if the input stream is redirected to a file and the end of file has been reached.
+ */
 public fun readLine(): String? = stdin.readLine()

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

@@ -14,13 +14,13 @@ public fun File.recurse(block: (File) -> Unit): Unit {
 }
 
 /**
- * Returns this if the file is a directory or the parent if it is a file inside a directory
+ * Returns `this` if this file is a directory, or the parent if it is a file inside a directory
  */
 public val File.directory: File
     get() = if (isDirectory()) this else getParentFile()!!
 
 /**
- * Returns the canonical path of the file
+ * Returns the canonical path of this file.
  */
 public val File.canonicalPath: String
     get() = getCanonicalPath()
@@ -38,7 +38,7 @@ public val File.path: String
     get() = getPath()
 
 /**
- * Returns file's extension or an empty string if it doesn't have one
+ * Returns the extension of this file (not including the dot), or an empty string if it doesn't have one.
  */
 public val File.extension: String
     get() {
@@ -46,14 +46,14 @@ public val File.extension: String
     }
 
 /**
- * Returns true if the given file is in the same directory or a descendant directory
+ * Returns true if the given [file] is in the same directory as this file or a descendant directory.
  */
 public fun File.isDescendant(file: File): Boolean {
     return file.directory.canonicalPath.startsWith(directory.canonicalPath)
 }
 
 /**
- * Returns the relative path of the given descendant of this file if it is a descendant
+ * Returns the relative path of the given descendant of this file if it is a descendant, or an empty string otherwise.
  */
 public fun File.relativePath(descendant: File): String {
     val prefix = directory.canonicalPath
@@ -69,7 +69,9 @@ public fun File.relativePath(descendant: File): String {
 }
 
 /**
- * Copies this file to the given output file, returning the number of bytes copied
+ * Copies this file to the given output [file].
+ * @param bufferSize the buffer size to use when copying.
+ * @return the number of bytes copied
  */
 public fun File.copyTo(file: File, bufferSize: Int = defaultBufferSize): Long {
     file.directory.mkdirs()
@@ -83,7 +85,7 @@ public fun File.copyTo(file: File, bufferSize: Int = defaultBufferSize): Long {
 }
 
 /**
- * Returns an array of files and directories in the directory that satisfy the specified filter
+ * Returns an array of files and directories in this directory that satisfy the specified [filter],
  * or null if this file does not denote a directory.
  */
 public fun File.listFiles(filter: (file: File) -> Boolean): Array<File>? = listFiles(

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

@@ -5,7 +5,7 @@ import java.nio.charset.Charset
 import java.nio.charset.CharsetDecoder
 import java.nio.charset.CharsetEncoder
 
-/** Returns an [Iterator] of bytes over an input stream */
+/** Returns an [Iterator] of bytes in this input stream. */
 public fun InputStream.iterator(): ByteIterator =
         object: ByteIterator() {
             override fun hasNext(): Boolean = available() > 0
@@ -13,39 +13,45 @@ public fun InputStream.iterator(): ByteIterator =
             public override fun nextByte(): Byte = read().toByte()
         }
 
-/** Creates a buffered input stream */
+/**
+ * Creates a buffered input stream wrapping this stream.
+ * @param bufferSize the buffer size to use.
+ */
 public fun InputStream.buffered(bufferSize: Int = defaultBufferSize): InputStream
         = if (this is BufferedInputStream)
     this
 else
     BufferedInputStream(this, bufferSize)
 
-/** Creates a reader on an input stream using UTF-8 or specified charset. */
+/** Creates a reader on this input stream using UTF-8 or the specified [charset]. */
 public fun InputStream.reader(charset: Charset = Charsets.UTF_8): InputStreamReader = InputStreamReader(this, charset)
 
-/** Creates a reader on an input stream using specified *charset* */
+/** Creates a reader on this input stream using the specified [charset]. */
 public fun InputStream.reader(charset: String): InputStreamReader = InputStreamReader(this, charset)
 
-/** Creates a reader on an input stream using specified *decoder* */
+/** Creates a reader on this input stream using the specified [decoder]. */
 public fun InputStream.reader(decoder: CharsetDecoder): InputStreamReader = InputStreamReader(this, decoder)
 
-/** Creates a buffered output stream */
+/**
+ * Creates a buffered output stream wrapping this stream.
+ * @param bufferSize the buffer size to use.
+ */
 public fun OutputStream.buffered(bufferSize: Int = defaultBufferSize): BufferedOutputStream
         = if (this is BufferedOutputStream) this else BufferedOutputStream(this, bufferSize)
 
-/** Creates a writer on an output stream using UTF-8 or specified charset. */
+/** Creates a writer on this output stream using UTF-8 or the specified [charset]. */
 public fun OutputStream.writer(charset: Charset = Charsets.UTF_8): OutputStreamWriter = OutputStreamWriter(this, charset)
 
-/** Creates a writer on an output stream using specified *charset* */
+/** Creates a writer on this output stream using the specified [charset]. */
 public fun OutputStream.writer(charset: String): OutputStreamWriter = OutputStreamWriter(this, charset)
 
-/** Creates a writer on an output stream using specified *encoder* */
+/** Creates a writer on this output stream using the specified [encoder]. */
 public fun OutputStream.writer(encoder: CharsetEncoder): OutputStreamWriter = OutputStreamWriter(this, encoder)
 
 /**
  * Copies this stream to the given output stream, returning the number of bytes copied
  *
- * **Note** it is the callers responsibility to close both of these resources
+ * **Note** It is the caller's responsibility to close both of these resources.
  */
 public fun InputStream.copyTo(out: OutputStream, bufferSize: Int = defaultBufferSize): Long {
     var bytesCopied: Long = 0
@@ -60,9 +66,9 @@ public fun InputStream.copyTo(out: OutputStream, bufferSize: Int = defaultBuffer
 }
 
 /**
- * Reads this stream completely into a byte array
+ * Reads this stream completely into a byte array.
  *
- * **Note** it is the callers responsibility to close this resource
+ * **Note**: It is the caller's responsibility to close this stream.
  */
 public fun InputStream.readBytes(estimatedSize: Int = defaultBufferSize): ByteArray {
     val buffer = ByteArrayOutputStream(estimatedSize)

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

@@ -7,12 +7,12 @@ import java.util.ArrayList
 import java.util.NoSuchElementException
 
 /**
- * Creates a new [[FileReader]] for this file
+ * Creates a new [FileReader] for reading the contents of this file.
  */
 public fun File.reader(): FileReader = FileReader(this)
 
 /**
- * Reads the entire content of the file as bytes
+ * Reads the entire content of this file as a byte array.
  *
  * This method is not recommended on huge files.
  */
@@ -21,66 +21,67 @@ public fun File.readBytes(): ByteArray {
 }
 
 /**
- * Writes the bytes as the contents of the file
+ * Replaces the contents of this file with [data].
  */
 public fun File.writeBytes(data: ByteArray): Unit {
     return FileOutputStream(this).use { it.write(data) }
 }
 
 /**
- * Appends bytes to the contents of the file.
+ * Appends [data] to the contents of this file.
  */
 public fun File.appendBytes(data: ByteArray): Unit {
     return FileOutputStream(this, true).use { it.write(data) }
 }
 
 /**
- * Reads the entire content of the file as a String using specified charset.
+ * Reads the entire content of this file as a String using specified [charset].
  *
  * This method is not recommended on huge files.
  */
 public fun File.readText(charset: String): String = readBytes().toString(charset)
 
 /**
- * Reads the entire content of the file as a String using UTF-8 or specified charset.
+ * Reads the entire content of this file as a String using UTF-8 or specified [charset].
  *
  * This method is not recommended on huge files.
  */
 public fun File.readText(charset: Charset = Charsets.UTF_8): String = readBytes().toString(charset)
 
 /**
- * Writes the text as the contents of the file using specified charset.
+ * Replaces the contents of this file with [text] encoded using the specified [charset].
  */
 public fun File.writeText(text: String, charset: String): Unit {
     writeBytes(text.toByteArray(charset))
 }
 
 /**
- * Writes the text as the contents of the file using UTF-8 or specified charset.
+ * Replaces the contents of this file with [text] encoded using UTF-8 or specified [charset].
  */
 public fun File.writeText(text: String, charset: Charset = Charsets.UTF_8): Unit {
     writeBytes(text.toByteArray(charset))
 }
 
 /**
- * Appends text to the contents of the file using UTF-8 or specified charset.
+ * Appends [text] to the contents of this file using UTF-8 or the specified [charset].
  */
 public fun File.appendText(text: String, charset: Charset = Charsets.UTF_8): Unit {
     appendBytes(text.toByteArray(charset))
 }
 
 /**
- * Appends text to the contents of the file using specified charset.
+ * Appends [text] to the contents of the file using the specified [charset].
  */
 public fun File.appendText(text: String, charset: String): Unit {
     appendBytes(text.toByteArray(charset))
 }
 
 /**
- * Reads file by byte blocks and calls closure for each block read. Block size depends on implementation but never less than 512.
- * This functions passes byte array and amount of bytes in this buffer to the closure function.
+ * Reads file by byte blocks and calls [closure] for each block read. Block size depends on implementation
+ * but is never less than 512 bytes.
+ * This functions passes the byte array and amount of bytes in this buffer to the [closure] function.
  *
- * You can use this function for huge files
+ * You can use this function for huge files.
  */
 public fun File.forEachBlock(closure: (ByteArray, Int) -> Unit): Unit {
     val arr = ByteArray(4096)
@@ -101,9 +102,9 @@ public fun File.forEachBlock(closure: (ByteArray, Int) -> Unit): Unit {
 }
 
 /**
- * Reads file line by line using specified [charset]. Default charset is UTF-8.
+ * Reads this file line by line using the specified [charset]. Default charset is UTF-8.
  *
- * You may use this function on huge files
+ * You may use this function on huge files.
  */
 public fun File.forEachLine(charset: Charset = Charsets.UTF_8, closure: (line: String) -> Unit): Unit {
     val reader = BufferedReader(InputStreamReader(FileInputStream(this), charset))
@@ -115,21 +116,21 @@ public fun File.forEachLine(charset: Charset = Charsets.UTF_8, closure: (line: S
 }
 
 /**
- * Reads file line by line using the specified [charset].
+ * Reads this file line by line using the specified [charset].
  *
- * You may use this function on huge files
+ * You may use this function on huge files.
  */
 public fun File.forEachLine(charset: String, closure: (line: String) -> Unit): Unit = forEachLine(Charset.forName(charset), closure)
 
 /**
- * Reads file content into list of lines using specified [charset]
+ * Reads the file content as a list of lines, using the specified [charset].
  *
  * Do not use this function for huge files.
  */
 public fun File.readLines(charset: String): List<String> = readLines(Charset.forName(charset))
 
 /**
- * Reads file content as strings list. By default uses UTF-8 charset.
+ * Reads the file content as a list of strings. By default uses UTF-8 charset.
  *
  * Do not use this function for huge files.
  */
@@ -139,29 +140,34 @@ public fun File.readLines(charset: Charset = Charsets.UTF_8): List<String> {
     return result
 }
 
-/** Creates a buffered reader, or returns self if Reader is already buffered */
+/** Creates a buffered reader wrapping this Reader, or returns self if Reader is already buffered */
 public fun Reader.buffered(bufferSize: Int = defaultBufferSize): BufferedReader
         = if (this is BufferedReader) this else BufferedReader(this, bufferSize)
 
-/** Creates a buffered writer, or returns self if Writer is already buffered */
+/** Creates a buffered writer wrapping this Writer, or returns self if Writer is already buffered */
 public fun Writer.buffered(bufferSize: Int = defaultBufferSize): BufferedWriter
         = if (this is BufferedWriter) this else BufferedWriter(this, bufferSize)
 
 /**
- * Iterates through each line of this reader then closing the [[Reader]] when its completed
+ * Iterates through each line of this reader and closes the [Reader] when it's completed
  */
 public fun Reader.forEachLine(block: (String) -> Unit): Unit = useLines { lines -> lines.forEach(block) }
 
+/**
+ * Calls the [block] callback giving it a stream of all the lines in this file and closes the reader once
+ * the processing is complete.
+ * @return the value returned by [block].
+ */
 public inline fun <T> Reader.useLines(block: (Stream<String>) -> T): T =
         this.buffered().use { block(it.lines()) }
 
 /**
  * Returns an iterator over each line.
- * <b>Note</b> the caller must close the underlying <code>BufferedReader</code>
+ * *Note*: the caller must close the underlying `BufferedReader`
  * when the iteration is finished; as the user may not complete the iteration loop (e.g. using a method like find() or any() on the iterator
  * may terminate the iteration early.
- * <br>
- * We suggest you try the method useLines() instead which closes the stream when the processing is complete.
+ *
+ * We suggest you try the method [useLines] instead which closes the stream when the processing is complete.
  */
 public fun BufferedReader.lines(): Stream<String> = LinesStream(this)
 
@@ -197,7 +203,7 @@ private class LinesStream(private val reader: BufferedReader) : Stream<String> {
 /**
  * Reads this reader completely as a String
  *
- * **Note** it is the callers responsibility to close this resource
+ * *Note*:  It is the caller's responsibility to close this resource.
  */
 public fun Reader.readText(): String {
     val buffer = StringWriter()
@@ -208,7 +214,7 @@ public fun Reader.readText(): String {
 /**
  * Copies this reader to the given output writer, returning the number of bytes copied.
  *
- * **Note** it is the callers responsibility to close both of these resources
+ * **Note** it is the caller's responsibility to close both of these resources
  */
 public fun Reader.copyTo(out: Writer, bufferSize: Int = defaultBufferSize): Long {
     var charsCopied: Long = 0
@@ -223,14 +229,14 @@ public fun Reader.copyTo(out: Writer, bufferSize: Int = defaultBufferSize): Long
 }
 
 /**
- * Reads the entire content of the URL as a String using specified charset.
+ * Reads the entire content of the URL as a String using the specified [charset].
  *
  * This method is not recommended on huge files.
  */
 public fun URL.readText(charset: String): String = readBytes().toString(charset)
 
 /**
- * Reads the entire content of the URL as a String using UTF-8 or specified charset..
+ * Reads the entire content of the URL as a String using UTF-8 or the specified [charset].
  *
  * This method is not recommended on huge files.
  */
@@ -243,7 +249,10 @@ public fun URL.readText(charset: Charset = Charsets.UTF_8): String = readBytes()
  */
 public fun URL.readBytes(): ByteArray = this.openStream()!!.use<InputStream, ByteArray>{ it.readBytes() }
 
-/** Uses the given resource then closes it down correctly whether an exception is thrown or not */
+/**
+ * Executes the given [block] on this resource and then closes it down correctly whether an exception
+ * is thrown or not
+ */
 public inline fun <T : Closeable, R> T.use(block: (T) -> R): R {
     var closed = false
     try {

libraries/stdlib/src/kotlin/jvm/JvmFlagAnnotations.kt

@@ -19,18 +19,39 @@ package kotlin.jvm
 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.
+ */
 Retention(RetentionPolicy.SOURCE)
 public annotation class volatile
 
+/**
+ * Marks the JVM backing field of the annotated property as `transient`, meaning that it is not
+ * part of the default serialized form of the object.
+ */
 Retention(RetentionPolicy.SOURCE)
 public annotation class transient
 
+/**
+ * Marks the JVM method generated from the annotated function as `strictfp`, meaning that the precision
+ * of floating point operations performed inside the method needs to be restricted in order to
+ * achieve better portability.
+ */
 Retention(RetentionPolicy.SOURCE)
 public annotation class strictfp
 
+/**
+ * Marks the JVM method generated from the annotated function as `synchronized`, meaning that the method
+ * will be protected from concurrent execution by multiple threads by the monitor of the instance (or,
+ * for static methods, the class) on which the method is defined.
+ */
 Retention(RetentionPolicy.SOURCE)
 public annotation class synchronized
 
+/**
+ * Marks the JVM method generated from the annotated function as `native`, meaning that it's not implemented
+ * in Java but rather in a different language (for example, in C/C++ using JNI).
+ */
 Retention(RetentionPolicy.SOURCE)
 public annotation class native
-

libraries/stdlib/src/kotlin/math/JMath.kt

@@ -3,25 +3,58 @@ package kotlin.math
 import java.math.BigInteger
 import java.math.BigDecimal
 
+/**
+ * Enables the use of the `+` operator for [BigInteger] instances.
+ */
 public fun BigInteger.plus(other: BigInteger) : BigInteger = this.add(other)
 
+/**
+ * Enables the use of the `-` operator for [BigInteger] instances.
+ */
 public fun BigInteger.minus(other: BigInteger) : BigInteger = this.subtract(other)
 
+/**
+ * Enables the use of the `*` operator for [BigInteger] instances.
+ */
 public fun BigInteger.times(other: BigInteger) : BigInteger = this.multiply(other)
 
+/**
+ * Enables the use of the `/` operator for [BigInteger] instances.
+ */
 public fun BigInteger.div(other: BigInteger) : BigInteger = this.divide(other)
 
+/**
+ * Enables the use of the unary `-` operator for [BigInteger] instances.
+ */
 public fun BigInteger.minus() : BigInteger = this.negate()
 
 
+/**
+ * Enables the use of the `+` operator for [BigDecimal] instances.
+ */
 public fun BigDecimal.plus(other: BigDecimal) : BigDecimal = this.add(other)
 
+/**
+ * Enables the use of the `-` operator for [BigDecimal] instances.
+ */
 public fun BigDecimal.minus(other: BigDecimal) : BigDecimal = this.subtract(other)
 
+/**
+ * Enables the use of the `*` operator for [BigDecimal] instances.
+ */
 public fun BigDecimal.times(other: BigDecimal) : BigDecimal = this.multiply(other)
 
+/**
+ * Enables the use of the `/` operator for [BigDecimal] instances.
+ */
 public fun BigDecimal.div(other: BigDecimal) : BigDecimal = this.divide(other)
 
+/**
+ * Enables the use of the `%` operator for [BigDecimal] instances.
+ */
 public fun BigDecimal.mod(other: BigDecimal) : BigDecimal = this.remainder(other)
 
-public fun BigDecimal.minus() : BigDecimal = this.negate()
+/**
+ * Enables the use of the unary `-` operator for [BigDecimal] instances.
+ */
+public fun BigDecimal.minus() : BigDecimal = this.negate()

libraries/stdlib/src/kotlin/platform/annotations.kt

@@ -16,6 +16,17 @@
 
 package kotlin.platform
 
+/**
+ * Specifies the name for the target platform element (Java class, method or field, JavaScript function)
+ * which is generated from this element.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/java-interop.html#handling-signature-clashes-with-platformname)
+ * for more information.
+ */
 public annotation class platformName(public val name: String)
 
-public annotation class platformStatic
+/**
+ * Specifies that a static method or field needs to be generated from this element.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/java-interop.html#static-methods-and-fields)
+ * for more information.
+ */
+public annotation class platformStatic

libraries/stdlib/src/kotlin/text/StringBuilderJVM.kt

@@ -5,7 +5,7 @@ import kotlin.properties.*
 /** Line separator for current system. */
 private val LINE_SEPARATOR: String by Delegates.lazy { System.getProperty("line.separator")!! }
 
-/** Appends line separator to Appendable. */
+/** Appends a line separator to this Appendable. */
 public fun Appendable.appendln(): Appendable = append(LINE_SEPARATOR)
 
 /** Appends value to the given Appendable and line separator after it. */
@@ -14,48 +14,47 @@ public fun Appendable.appendln(value: CharSequence?): Appendable = append(value)
 /** Appends value to the given Appendable and line separator after it. */
 public fun Appendable.appendln(value: Char): Appendable = append(value).append(LINE_SEPARATOR)
 
-/** Appends line separator to StringBuilder. */
-
+/** Appends a line separator to this StringBuilder. */
 public fun StringBuilder.appendln(): StringBuilder = append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: StringBuffer?): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: CharSequence?): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: String?): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Any?): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: StringBuilder?): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: CharArray): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Char): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Boolean): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Int): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Short): StringBuilder = append(value.toInt()).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Byte): StringBuilder = append(value.toInt()).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Long): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Float): StringBuilder = append(value).append(LINE_SEPARATOR)
 
-/** Appends value to the given StringBuilder and line separator after it. */
+/** Appends value to this StringBuilder and line separator after it. */
 public fun StringBuilder.appendln(value: Double): StringBuilder = append(value).append(LINE_SEPARATOR)

libraries/stdlib/src/kotlin/text/StringsJVM.kt

@@ -143,7 +143,7 @@ deprecated("Use toByteArray(charset) instead to emphasize copy behaviour")
 public fun String.getBytes(charset: String): ByteArray = (this as java.lang.String).getBytes(charset)
 
 /**
- * Returns a subsequence specified by given range.
+ * Returns a subsequence specified by given [range].
  */
 public fun CharSequence.slice(range: IntRange): CharSequence {
     return subSequence(range.start, range.end + 1) // inclusive
@@ -158,31 +158,36 @@ public fun String.toRegex(flags: Int = 0): java.util.regex.Pattern {
     return java.util.regex.Pattern.compile(this, flags)
 }
 
+/**
+ * Creates a new [StringReader] for reading the contents of this string.
+ */
 public val String.reader: StringReader
     get() = StringReader(this)
 
 /**
- * Returns a copy of this string capitalised if it is not empty or already starting with an uppper case letter, otherwise returns this
+ * Returns a copy of this string capitalised if it is not empty or already starting with an upper case letter,
+ * otherwise returns this.
  *
- * @includeFunctionBody ../../test/text/StringTest.kt capitalize
+ * @sample test.text.StringJVMTest.capitalize
  */
 public fun String.capitalize(): String {
     return if (isNotEmpty() && charAt(0).isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this
 }
 
 /**
- * Returns a copy of this string with the first letter lower case if it is not empty or already starting with a lower case letter, otherwise returns this
+ * Returns a copy of this string with the first letter lowercased if it is not empty or already starting with
+ * a lower case letter, otherwise returns this.
  *
- * @includeFunctionBody ../../test/text/StringTest.kt decapitalize
+ * @sample test.text.StringJVMTest.decapitalize
  */
 public fun String.decapitalize(): String {
     return if (isNotEmpty() && charAt(0).isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this
 }
 
 /**
- * Repeats a given string n times.
- * When n < 0, IllegalArgumentException is thrown.
- * @includeFunctionBody ../../test/text/StringTest.kt repeat
+ * Repeats a given string [n] times.
+ * @throws IllegalArgumentException when n < 0
+ * @sample test.text.StringJVMTest.repeat
  */
 public fun String.repeat(n: Int): String {
     if (n < 0)
@@ -196,9 +201,8 @@ public fun String.repeat(n: Int): String {
 }
 
 /**
- * Returns an Appendable containing the everything but the first characters that satisfy the given *predicate*
- *
- * @includeFunctionBody ../../test/text/StringTest.kt dropWhile
+ * Appends the contents of this string, excluding the first characters that satisfy the given [predicate],
+ * to the given Appendable.
  */
 public inline fun <T : Appendable> String.dropWhileTo(result: T, predicate: (Char) -> Boolean): T {
     var start = true
@@ -214,9 +218,7 @@ public inline fun <T : Appendable> String.dropWhileTo(result: T, predicate: (Cha
 }
 
 /**
- * Returns an Appendable containing the first characters that satisfy the given *predicate*
- *
- * @includeFunctionBody ../../test/text/StringTest.kt takeWhile
+ * Appends the first characters from this string that satisfy the given [predicate] to the given Appendable.
  */
 public inline fun <T : Appendable> String.takeWhileTo(result: T, predicate: (Char) -> Boolean): T {
     for (c in this) if (predicate(c)) result.append(c) else break
@@ -224,8 +226,8 @@ public inline fun <T : Appendable> String.takeWhileTo(result: T, predicate: (Cha
 }
 
 /**
- * Replaces every *regexp* occurence in the text with the value retruned by the given function *body* that can handle
- * particular occurance using [[MatchResult]] provided.
+ * Replaces every [regexp] occurence in the text with the value returned by the given function [body] that
+ * takes a [MatchResult].
  */
 public fun String.replaceAll(regexp: String, body: (java.util.regex.MatchResult) -> String): String {
     val sb = StringBuilder(this.length())