Standard library documentation continued.

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)
 }