Standard library documentation continued.

core/builtins/native/kotlin/Boolean.kt

@@ -16,6 +16,10 @@
 
 package kotlin
 
+/**
+ * Represents a value which is either `true` or `false`. On the JVM, non-nullable values of this type are
+ * represented as values of the primitive type `boolean`.
+ */
 public class Boolean private () : Comparable<Boolean> {
     public fun not(): Boolean
 

core/builtins/native/kotlin/Char.kt

@@ -16,6 +16,10 @@
 
 package kotlin
 
+/**
+ * Represents a singe 16-bit Unicode character. On the JVM, non-nullable values of this type are represented
+ * as values of the primitive type `char`.
+ */
 public class Char private () : Comparable<Char> {
     public fun compareTo(other: Double): Int
     public fun compareTo(other: Float) : Int

core/builtins/native/kotlin/CharSequence.kt

@@ -16,10 +16,25 @@
 
 package kotlin
 
+/**
+ * Represents a readable sequence of [Char] values.
+ */
 public trait CharSequence {
+    /**
+     * Returns the length of this character sequence.
+     */
     public fun length(): Int
 
+    /**
+     * Returns the character at the specified [index] in the sequence.
+     */
     public fun charAt(index: Int): Char
 
+    /**
+     * Returns a subsequence of this sequence.
+     *
+     * @param start the start index (inclusive).
+     * @param end the end index (exclusive).
+     */
     public fun subSequence(start: Int, end: Int): CharSequence
 }

core/builtins/native/kotlin/Cloneable.kt

@@ -16,6 +16,12 @@
 
 package kotlin
 
+/**
+ * Classes that inherit from this trait support creating field-by-field copies of their instances.
+ */
 public trait Cloneable {
+    /**
+     * Creates and returns a field-by-field copy of this object.
+     */
     protected fun clone(): Any { /* intrinsic */ }
 }

core/builtins/native/kotlin/Collections.kt

@@ -16,40 +16,115 @@
 
 package kotlin
 
+/**
+ * Classes that inherit from this trait can be represented as a sequence of elements that can
+ * be iterated over.
+ * @param T the type of element being iterated over.
+ */
 public trait Iterable<out T> {
+    /**
+     * Returns an iterator over the elements of this object.
+     */
     public fun iterator(): Iterator<T>
 }
 
+/**
+ * Classes that inherit from this trait can be represented as a sequence of elements that can
+ * be iterated over and that supports removing elements during iteration.
+ */
 public trait MutableIterable<out T> : Iterable<T> {
+    /**
+     * Returns an iterator over the elementrs of this sequence that supports removing elements during iteration.
+     */
     override fun iterator(): MutableIterator<T>
 }
 
+/**
+ * A generic collection of elements. Methods in this trait support only read-only access to the collection;
+ * read/write access is supported through the [MutableCollection] trait.
+ * @param E the type of elements contained in the collection.
+ */
 public trait Collection<out E> : Iterable<E> {
     // Query Operations
+    /**
+     * Returns the size of the collection.
+     */
     public fun size(): Int
+
+    /**
+     * Returns `true` if the collection is empty (contains no elements), `false` otherwise.
+     */
     public fun isEmpty(): Boolean
+
+    /**
+     * Checks if the specified element is contained in this collection.
+     */
     public fun contains(o: Any?): Boolean
     override fun iterator(): Iterator<E>
 
     // Bulk Operations
+    /**
+     * Checks if all elements in the specified collection are contained in this collection.
+     */
     public fun containsAll(c: Collection<Any?>): Boolean
 }
 
+/**
+ * A generic collection of elements that supports adding and removing elements.
+ */
 public trait MutableCollection<E> : Collection<E>, MutableIterable<E> {
     // Query Operations
     override fun iterator(): MutableIterator<E>
 
     // Modification Operations
+    /**
+     * Adds the specified element to the collection.
+     *
+     * @return `true` if the element has been added, `false` if the collection does not support duplicates
+     * and the element is already contained in the collection.
+     */
     public fun add(e: E): Boolean
+
+    /**
+     * Removes the specified element from the collection.
+     *
+     * @return `true` if the element has been successfully removed; `false` if it was not present in the collection.
+     */
     public fun remove(o: Any?): Boolean
 
     // Bulk Modification Operations
+    /**
+     * Adds all of the elements in the specified collection to this collection.
+     *
+     * @return `true` if any of the specified elements was added to the collection, `false` if the collection was not modified.
+     */
     public fun addAll(c: Collection<E>): Boolean
+
+    /**
+     * Removes all of the elements in the specified collection from this collection.
+     *
+     * @return `true` if any of the specified elements was removed from the collection, `false` if the collection was not modified.
+     */
     public fun removeAll(c: Collection<Any?>): Boolean
+
+    /**
+     * Removes all of the elements not contained in the specified collection from this collection.
+     *
+     * @return `true` if any element was removed from the collection, `false` if the collection was not modified.
+     */
     public fun retainAll(c: Collection<Any?>): Boolean
+
+    /**
+     * Removes all elements from this collection.
+     */
     public fun clear(): Unit
 }
 
+/**
+ * A generic ordered collection of elements. Methods in this trait support only read-only access to the list;
+ * read/write access is supported through the [MutableList] trait.
+ * @param E the type of elements contained in the list.
+ */
 public trait List<out E> : Collection<E> {
     // Query Operations
     override fun size(): Int
@@ -61,20 +136,47 @@ public trait List<out E> : Collection<E> {
     override fun containsAll(c: Collection<Any?>): Boolean
 
     // Positional Access Operations
+    /**
+     * Returns the element at the specified index in the list.
+     */
     public fun get(index: Int): E
 
     // Search Operations
+    /**
+     * Returns the index of the first occurrence of the specified element in the list, or -1 if the specified
+     * element is not contained in the list.
+     */
     public fun indexOf(o: Any?): Int
+
+    /**
+     * Returns the index of the last occurrence of the specified element in the list, or -1 if the specified
+     * element is not contained in the list.
+     */
     public fun lastIndexOf(o: Any?): Int
 
     // List Iterators
+    /**
+     * Returns a list iterator over the elements in this list (in proper sequence).
+     */
     public fun listIterator(): ListIterator<E>
+
+    /**
+     * Returns a list iterator over the elements in this list (in proper sequence), starting at the specified [index].
+     */
     public fun listIterator(index: Int): ListIterator<E>
 
     // View
+    /**
+     * Returns a view of the portion of this list between the specified [fromIndex] (inclusive) and [toIndex] (exclusive).
+     * The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
+     */
     public fun subList(fromIndex: Int, toIndex: Int): List<E>
 }
 
+/**
+ * A generic ordered collection of elements that supports adding and removing elements.
+ * @param E the type of elements contained in the list.
+ */
 public trait MutableList<E> : List<E>, MutableCollection<E> {
     // Modification Operations
     override fun add(e: E): Boolean
@@ -82,14 +184,35 @@ public trait MutableList<E> : List<E>, MutableCollection<E> {
 
     // Bulk Modification Operations
     override fun addAll(c: Collection<E>): Boolean
+
+    /**
+     * Inserts all of the elements in the specified collection [c] into this list at the specified [index].
+     *
+     * @return `true` if the list was changed as the result of the operation.
+     */
     public fun addAll(index: Int, c: Collection<E>): Boolean
     override fun removeAll(c: Collection<Any?>): Boolean
     override fun retainAll(c: Collection<Any?>): Boolean
     override fun clear(): Unit
 
     // Positional Access Operations
+    /**
+     * Replaces the element at the specified position in this list with the specified element.
+     *
+     * @return the element previously at the specified position.
+     */
     public fun set(index: Int, element: E): E
+
+    /**
+     * Inserts an element into the list at the specified [index].
+     */
     public fun add(index: Int, element: E): Unit
+
+    /**
+     * Removes an element at the specified [index] from the list.
+     *
+     * @return the element that has been removed.
+     */
     public fun remove(index: Int): E
 
     // List Iterators
@@ -100,6 +223,12 @@ public trait MutableList<E> : List<E>, MutableCollection<E> {
     override fun subList(fromIndex: Int, toIndex: Int): MutableList<E>
 }
 
+/**
+ * A generic unordered collection of elements that does not support duplicate elements.
+ * Methods in this trait support only read-only access to the set;
+ * read/write access is supported through the [MutableSet] trait.
+ * @param E the type of elements contained in the set.
+ */
 public trait Set<out E> : Collection<E> {
     // Query Operations
     override fun size(): Int
@@ -111,6 +240,11 @@ public trait Set<out E> : Collection<E> {
     override fun containsAll(c: Collection<Any?>): Boolean
 }
 
+/**
+ * A generic unordered collection of elements that does not support duplicate elements, and supports
+ * adding and removing elements.
+ * @param E the type of elements contained in the set.
+ */
 public trait MutableSet<E> : Set<E>, MutableCollection<E> {
     // Query Operations
     override fun iterator(): MutableIterator<E>
@@ -126,32 +260,104 @@ public trait MutableSet<E> : Set<E>, MutableCollection<E> {
     override fun clear(): Unit
 }
 
+/**
+ * A collection that holds pairs of objects (keys and values) and supports efficiently retrieving
+ * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
+ * Methods in this trait support only read-only access to the map; read-write access is supported through
+ * the [MutableMap] trait.
+ * @param K the type of map keys.
+ * @param V the type of map values.
+ */
 public trait Map<K, out V> {
     // Query Operations
+    /**
+     * Returns the number of key/value pairs in the map.
+     */
     public fun size(): Int
+
+    /**
+     * Returns `true` if the map is empty (contains no elements), `false` otherwise.
+     */
     public fun isEmpty(): Boolean
+
+    /**
+     * Returns `true` if the map contains the specified [key].
+     */
     public fun containsKey(key: Any?): Boolean
+
+    /**
+     * Returns `true` if the map maps one or more keys to the specified [value].
+     */
     public fun containsValue(value: Any?): Boolean
+
+    /**
+     * Returns the value corresponding to the given [key], or `null` if such a key is not present in the map.
+     */
     public fun get(key: Any?): V?
 
     // Views
+    /**
+     * Returns a [Set] of all keys in this map.
+     */
     public fun keySet(): Set<K>
+
+    /**
+     * Returns a [Collection] of all values in this map. Note that this collection may contain duplicate values.
+     */
     public fun values(): Collection<V>
+
+    /**
+     * Returns a [Set] of all key/value pairs in this map.
+     */
     public fun entrySet(): Set<Map.Entry<K, V>>
 
+    /**
+     * Represents a key/value pair held by a [Map].
+     */
     public trait Entry<out K, out V> {
+        /**
+         * Returns the key of this key/value pair.
+         */
         public fun getKey(): K
+
+        /**
+         * Returns the value of this key/value pair.
+         */
         public fun getValue(): V
     }
 }
 
+/**
+ * A modifiable collection that holds pairs of objects (keys and values) and supports efficiently retrieving
+ * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
+ * @param K the type of map keys.
+ * @param V the type of map values.
+ */
 public trait MutableMap<K, V> : Map<K, V> {
     // Modification Operations
+    /**
+     * Associates the specified [value] with the specified [key] in the map.
+     *
+     * @return the previous value associated with the key, or `null` if the key was not present in the map.
+     */
     public fun put(key: K, value: V): V?
+
+    /**
+     * Removes the specified key and its corresponding value from this map.
+     *
+     * @return the previous value associated with the key, or `null` if the key was not present in the map.
+     */
     public fun remove(key: Any?): V?
 
     // Bulk Modification Operations
+    /**
+     * Updates this map with key/value pairs from the specified map [m].
+     */
     public fun putAll(m: Map<out K, V>): Unit
+
+    /**
+     * Removes all elements from this map.
+     */
     public fun clear(): Unit
 
     // Views
@@ -159,7 +365,15 @@ public trait MutableMap<K, V> : Map<K, V> {
     override fun values(): MutableCollection<V>
     override fun entrySet(): MutableSet<MutableMap.MutableEntry<K, V>>
 
+    /**
+     * Represents a key/value pair held by a [MutableMap].
+     */
     public trait MutableEntry<K,V>: Map.Entry<K, V> {
+        /**
+         * Changes the value associated with the key of this entry.
+         *
+         * @return the previous value corresponding to the key.
+         */
     	public fun setValue(value: V): V
     }
 }

core/builtins/native/kotlin/Comparable.kt

@@ -16,6 +16,14 @@
 
 package kotlin
 
+/**
+ * Classes which inherit from this trait have a defined total ordering between their instances.
+ */
 public trait Comparable<in T> {
+    /**
+     * Compares this object with the specified object for order. Returns zero if this object is equal
+     * to the specified [other] object, a negative number if it's less than [other], or a positive number
+     * if it's greater than [other].
+     */
     public fun compareTo(other: T): Int
 }

core/builtins/native/kotlin/Enum.kt

@@ -16,8 +16,21 @@
 
 package kotlin
 
+/**
+ * The common base class of all enum classes.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/enum-classes.html) for more
+ * information on enum classes.
+ */
 public abstract class Enum<E : Enum<E>>(name: String, ordinal: Int): Comparable<E> {
+    /**
+     * Returns the name of this enum constant, exactly as declared in its enum declaration.
+     */
     public final fun name(): String
+
+    /**
+     * Returns the ordinal of this enumeration constant (its position in its enum declaration, where the initial constant
+     * is assigned an ordinal of zero).
+     */
     public final fun ordinal(): Int
 
     public override final fun compareTo(other: E): Int

core/builtins/native/kotlin/Numbers.kt

@@ -16,16 +16,50 @@
 
 package kotlin
 
+/**
+ * Superclass for all platform classes representing numeric values.
+ */
 public abstract class Number {
+    /**
+     * Returns the value of this number as a [Double], which may involve rounding.
+     */
     public abstract fun toDouble(): Double
+
+    /**
+     * Returns the value of this number as a [Float], which may involve rounding.
+     */
     public abstract fun toFloat(): Float
+
+    /**
+     * Returns the value of this number as a [Long], which may involve rounding or truncation.
+     */
     public abstract fun toLong(): Long
+
+    /**
+     * Returns the value of this number as an [Int], which may involve rounding or truncation.
+     */
     public abstract fun toInt(): Int
+
+    /**
+     * Returns the [Char] with the numeric value equal to this number, truncated to 16 bits if appropriate.
+     */
     public abstract fun toChar(): Char
+
+    /**
+     * Returns the value of this number as a [Short], which may involve rounding or truncation.
+     */
     public abstract fun toShort(): Short
+
+    /**
+     * Returns the value of this number as a [Byte], which may involve rounding or truncation.
+     */
     public abstract fun toByte(): Byte
 }
 
+/**
+ * Represents a double-precision 64-bit IEEE 754 floating point number. On the JVM, non-nullable
+ * values of this type are represented as values of the primitive type `double`.
+ */
 public class Double private () : Number, Comparable<Double> {
     public override fun compareTo(other: Double): Int
     public fun compareTo(other: Float): Int
@@ -96,6 +130,10 @@ public class Double private () : Number, Comparable<Double> {
     public override fun toByte(): Byte
 }
 
+/**
+ * Represents a single-precision 32-bit IEEE 754 floating point number.  On the JVM, non-nullable
+ * values of this type are represented as values of the primitive type `float`.
+ */
 public class Float private () : Number, Comparable<Float> {
     public fun compareTo(other: Double): Int
     public override fun compareTo(other: Float): Int
@@ -167,6 +205,10 @@ public class Float private () : Number, Comparable<Float> {
     public override fun toByte(): Byte
 }
 
+/**
+ * Represents a 64-bit signed integer. On the JVM, non-nullable values of this type are represented
+ * as values of the primitive type `long`.
+ */
 public class Long private () : Number, Comparable<Long> {
     public fun compareTo(other: Double): Int
     public fun compareTo(other: Float) : Int
@@ -246,6 +288,10 @@ public class Long private () : Number, Comparable<Long> {
     public override fun toByte(): Byte
 }
 
+/**
+ * Represents a 32-bit signed integer. On the JVM, non-nullable values of this type are represented
+ * as values of the primitive type `int`.
+ */
 public class Int private () : Number, Comparable<Int> {
     public fun compareTo(other: Double): Int
     public fun compareTo(other: Float) : Int
@@ -325,6 +371,10 @@ public class Int private () : Number, Comparable<Int> {
     public override fun toByte(): Byte
 }
 
+/**
+ * Represents a 16-bit signed integer. On the JVM, non-nullable values of this type are represented
+ * as values of the primitive type `short`.
+ */
 public class Short private () : Number, Comparable<Short> {
     public fun compareTo(other: Double): Int
     public fun compareTo(other: Float) : Int
@@ -396,6 +446,10 @@ public class Short private () : Number, Comparable<Short> {
     public override fun toByte(): Byte
 }
 
+/**
+ * Represents a 8-bit signed integer. On the JVM, non-nullable values of this type are represented
+ * as values of the primitive type `byte`.
+ */
 public class Byte private () : Number, Comparable<Byte> {
     public fun compareTo(other: Double): Int
     public fun compareTo(other: Float) : Int

core/builtins/native/kotlin/String.kt

@@ -21,8 +21,14 @@ package kotlin
  * implemented as instances of this class.
  */
 public class String : Comparable<String>, CharSequence {
+    /**
+     * Returns a string obtained by concatenating this string with the string representation of the given [other] object.
+     */
     public fun plus(other: Any?): String
 
+    /**
+     * Returns the character at the specified [index].
+     */
     public fun get(index: Int): Char
 
     public override fun length(): Int

core/builtins/native/kotlin/Throwable.kt

@@ -16,10 +16,25 @@
 
 package kotlin
 
+/**
+ * The base class for all errors and exceptions. Only instances of this class can be thrown or caught.
+ *
+ * @param message the detail message string.
+ * @param cause the cause of this throwable.
+ */
 public open class Throwable(message: String? = null, cause: Throwable? = null) {
+    /**
+     * Returns the detail message of this throwable.
+     */
     public fun getMessage(): String?
 
+    /**
+     * Returns the cause of this throwable.
+     */
     public fun getCause(): Throwable?
 
+    /**
+     * Prints the stack trace of this throwable to the standard output.
+     */
     public fun printStackTrace(): Unit
 }

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

@@ -12,20 +12,44 @@ import kotlin.jvm.internal.Intrinsic
 [Intrinsic("kotlin.arrays.array")] public fun <reified T> array(vararg t : T) : Array<T> = t as Array<T>
 
 // "constructors" for primitive types array
+/**
+ * Returns an array containing the specified [Double] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun doubleArray(vararg content : Double) : DoubleArray    = content
 
+/**
+ * Returns an array containing the specified [Float] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun floatArray(vararg content : Float) : FloatArray       = content
 
+/**
+ * Returns an array containing the specified [Long] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun longArray(vararg content : Long) : LongArray          = content
 
+/**
+ * Returns an array containing the specified [Int] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun intArray(vararg content : Int) : IntArray             = content
 
+/**
+ * Returns an array containing the specified characters.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun charArray(vararg content : Char) : CharArray          = content
 
+/**
+ * Returns an array containing the specified [Short] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun shortArray(vararg content : Short) : ShortArray       = content
 
+/**
+ * Returns an array containing the specified [Byte] numbers.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun byteArray(vararg content : Byte) : ByteArray          = content
 
+/**
+ * Returns an array containing the specified boolean values.
+ */
 [Intrinsic("kotlin.arrays.array")] public fun booleanArray(vararg content : Boolean) : BooleanArray = content
 
 /**

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

@@ -21,6 +21,10 @@ public fun <T> Iterator<T>.iterator(): Iterator<T> = this
  */
 public data class IndexedValue<out T>(public val index: Int, public val value: T)
 
+/**
+ * A wrapper over another [Iterable] (or any other object that can produce an [Iterator]) that returns
+ * an indexing iterator.
+ */
 public class IndexingIterable<out T>(private val iteratorFactory: () -> Iterator<T>) : Iterable<IndexedValue<T>> {
     override fun iterator(): Iterator<IndexedValue<T>> = IndexingIterator(iteratorFactory())
 }

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

@@ -12,6 +12,13 @@ public fun <T> streamOf(progression: Progression<T>): Stream<T> = object : Strea
     override fun iterator(): Iterator<T> = progression.iterator()
 }
 
+/**
+ * A stream that returns the values from the underlying [stream] that either match or do not match
+ * the specified [predicate].
+ *
+ * @param sendWhen If `true`, values for which the predicate returns `true` are returned. Otherwise,
+ * values for which the predicate returns `false` are returned
+ */
 public class FilteringStream<T>(private val stream: Stream<T>,
                                 private val sendWhen: Boolean = true,
                                 private val predicate: (T) -> Boolean
@@ -78,6 +85,10 @@ public class TransformingIndexedStream<T, R>(private val stream: Stream<T>, priv
     }
 }
 
+/**
+ * A stream which combines values from the underlying [stream] with their indices and returns them as
+ * [IndexedValue] objects.
+ */
 public class IndexingStream<T>(private val stream: Stream<T>) : Stream<IndexedValue<T>> {
     override fun iterator(): Iterator<IndexedValue<T>> = object : Iterator<IndexedValue<T>> {
         val iterator = stream.iterator()
@@ -248,6 +259,10 @@ public class TakeWhileStream<T>(private val stream: Stream<T>,
     }
 }
 
+/**
+ * A stream that skips the specified number of values from the underlying stream and returns
+ * all values after that.
+ */
 public class DropStream<T>(private val stream: Stream<T>,
                            private val count: Int
                           ) : Stream<T> {
@@ -280,6 +295,10 @@ public class DropStream<T>(private val stream: Stream<T>,
     }
 }
 
+/**
+ * A stream that skips the values from the underlying stream while the given [predicate] returns `true` and returns
+ * all values after that.
+ */
 public class DropWhileStream<T>(private val stream: Stream<T>,
                                 private val predicate: (T) -> Boolean
                                ) : Stream<T> {
@@ -322,6 +341,10 @@ public class DropWhileStream<T>(private val stream: Stream<T>,
     }
 }
 
+/**
+ * A stream which repeatedly calls the specified [producer] function and returns its return values, until
+ * `null` is returned from [producer].
+ */
 public class FunctionStream<T : Any>(private val producer: () -> T?) : Stream<T> {
     override fun iterator(): Iterator<T> = object : Iterator<T> {
         var nextState: Int = -1 // -1 for unknown, 0 for done, 1 for continue

libraries/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt

@@ -18,8 +18,10 @@ package kotlin.jvm.internal.unsafe
 
 import kotlin.jvm.internal.Intrinsic
 
+/** @suppress */
 [Intrinsic("kotlin.jvm.internal.unsafe.monitorEnter")]
 public fun monitorEnter(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")
 
+/** @suppress */
 [Intrinsic("kotlin.jvm.internal.unsafe.monitorExit")]
 public fun monitorExit(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")

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

@@ -3,6 +3,8 @@ package kotlin
 import java.io.StringReader
 import java.util.ArrayList
 import java.util.Locale
+import java.util.regex.MatchResult
+import java.util.regex.Pattern
 import java.nio.charset.Charset
 
 public fun String.lastIndexOf(str: String): Int = (this as java.lang.String).lastIndexOf(str)
@@ -128,6 +130,12 @@ public fun String.toDouble(): Double = java.lang.Double.parseDouble(this)
 
 public fun String.toCharList(): List<Char> = toCharArray().toList()
 
+/**
+ * Returns a subsequence of this sequence.
+ *
+ * @param start the start index (inclusive).
+ * @param end the end index (exclusive).
+ */
 public fun CharSequence.get(start: Int, end: Int): CharSequence = subSequence(start, end)
 
 public fun String.toByteArray(charset: String): ByteArray = (this as java.lang.String).getBytes(charset)
@@ -150,8 +158,8 @@ public fun CharSequence.slice(range: IntRange): CharSequence {
 }
 
 /**
- * Converts the string into a regular expression [[Pattern]] optionally
- * with the specified flags from [[Pattern]] or'd together
+ * Converts the string into a regular expression [Pattern] optionally
+ * with the specified flags from [Pattern] or'd together
  * so that strings can be split or matched on.
  */
 public fun String.toRegex(flags: Int = 0): java.util.regex.Pattern {
@@ -168,7 +176,7 @@ public val String.reader: StringReader
  * Returns a copy of this string capitalised if it is not empty or already starting with an upper case letter,
  * otherwise returns this.
  *
- * @sample test.text.StringJVMTest.capitalize
+ * @sample test.text.StringTest.capitalize
  */
 public fun String.capitalize(): String {
     return if (isNotEmpty() && charAt(0).isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this
@@ -178,7 +186,7 @@ public fun String.capitalize(): String {
  * 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.
  *
- * @sample test.text.StringJVMTest.decapitalize
+ * @sample test.text.StringTest.decapitalize
  */
 public fun String.decapitalize(): String {
     return if (isNotEmpty() && charAt(0).isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this

libraries/stdlib/src/kotlin/util/Ordering.kt

@@ -51,8 +51,8 @@ public fun <T : Comparable<*>> compareValues(a: T?, b: T?): Int {
 
 /**
  * Creates a comparator using the sequence of functions to calculate a result of comparison.
- * The functions are called sequentially, receive the given values [a] and [b] and return [Comparable]
- * objects. As soon as the [Comparable] instances returned by a function for [a] and [b] values do not
+ * The functions are called sequentially, receive the given values `a` and `b` and return [Comparable]
+ * objects. As soon as the [Comparable] instances returned by a function for `a` and `b` values do not
  * compare as equal, the result of that comparison is returned from the [Comparator].
  */
 public fun <T> compareBy(vararg functions: (T) -> Comparable<*>?): Comparator<T> {

libraries/stdlib/src/kotlin/util/Ranges.kt

@@ -1,5 +1,8 @@
 package kotlin
 
+/**
+ * Represents a range of [Comparable] values.
+ */
 public class ComparableRange<T: Comparable<T>> (
         override val start: T,
         override val end: T
@@ -18,6 +21,10 @@ public class ComparableRange<T: Comparable<T>> (
     }
 }
 
+/**
+ * Creates a range from this [Comparable] value to the specified [that] value. This value
+ * needs to be smaller than [that] value, otherwise the returned range will be empty.
+ */
 public fun <T: Comparable<T>> T.rangeTo(that: T): ComparableRange<T> {
     return ComparableRange(this, that)
 }

libraries/stdlib/test/collections/ListSpecificTest.kt

@@ -28,7 +28,7 @@ class ListSpecificTest {
         assertEquals(listOf('C', 'A', 'D'), list.slice(iter))
     }
 
-    Test fun utils() {
+    Test fun lastIndex() {
         assertEquals(-1, empty.lastIndex)
         assertEquals(1, data.lastIndex)
     }