More standard library documentation.

core/builtins/native/kotlin/Arrays.kt

@@ -19,7 +19,7 @@
 package kotlin
 
 /**
- * An array of bytes. When targeting the JVM, instances of this class are represented as byte[].
+ * An array of bytes. When targeting the JVM, instances of this class are represented as `byte[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class ByteArray(size: Int) : Cloneable {
@@ -38,7 +38,7 @@ public class ByteArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of chars. When targeting the JVM, instances of this class are represented as char[].
+ * An array of chars. When targeting the JVM, instances of this class are represented as `char[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class CharArray(size: Int) : Cloneable {
@@ -57,7 +57,7 @@ public class CharArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of shorts. When targeting the JVM, instances of this class are represented as short[].
+ * An array of shorts. When targeting the JVM, instances of this class are represented as `short[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class ShortArray(size: Int) : Cloneable {
@@ -76,7 +76,7 @@ public class ShortArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of ints. When targeting the JVM, instances of this class are represented as int[].
+ * An array of ints. When targeting the JVM, instances of this class are represented as `int[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class IntArray(size: Int) : Cloneable {
@@ -95,7 +95,7 @@ public class IntArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of longs. When targeting the JVM, instances of this class are represented as long[].
+ * An array of longs. When targeting the JVM, instances of this class are represented as `long[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class LongArray(size: Int) : Cloneable {
@@ -114,7 +114,7 @@ public class LongArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of floats. When targeting the JVM, instances of this class are represented as float[].
+ * An array of floats. When targeting the JVM, instances of this class are represented as `float[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class FloatArray(size: Int) : Cloneable {
@@ -133,7 +133,7 @@ public class FloatArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of doubles. When targeting the JVM, instances of this class are represented as double[].
+ * An array of doubles. When targeting the JVM, instances of this class are represented as `double[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 public class DoubleArray(size: Int) : Cloneable {
@@ -152,7 +152,7 @@ public class DoubleArray(size: Int) : Cloneable {
 }
 
 /**
- * An array of booleans. When targeting the JVM, instances of this class are represented as boolean[].
+ * An array of booleans. When targeting the JVM, instances of this class are represented as `boolean[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to false.
  */
 public class BooleanArray(size: Int) : Cloneable {

core/builtins/native/kotlin/Boolean.kt

@@ -21,12 +21,24 @@ package kotlin
  * represented as values of the primitive type `boolean`.
  */
 public class Boolean private () : Comparable<Boolean> {
+    /**
+     * Returns the inverse of this boolean.
+     */
     public fun not(): Boolean
 
+    /**
+     * Performs a logical `and` operation between this Boolean and the [other] one.
+     */
     public fun and(other: Boolean): Boolean
 
+    /**
+     * Performs a logical `or` operation between this Boolean and the [other] one.
+     */
     public fun or(other: Boolean): Boolean
 
+    /**
+     * Performs a logical `xor` operation between this Boolean and the [other] one.
+     */
     public fun xor(other: Boolean): Boolean
 
     public override fun compareTo(other: Boolean): Int

core/builtins/src/kotlin/Annotations.kt

@@ -26,13 +26,13 @@ public annotation class data
 
 /**
  * Marks the annotated class, function or property as deprecated.
- * @param value the message explaining the deprecation and recommending an alternative API to use.
+ * @property value the message explaining the deprecation and recommending an alternative API to use.
  */
 public annotation class deprecated(val value: String)
 
 /**
  * Suppresses the given compilation warnings in the annotated element.
- * @param names names of the compiler diagnostics to suppress.
+ * @property names names of the compiler diagnostics to suppress.
  */
 public annotation class suppress(vararg val names: String)
 

core/builtins/src/kotlin/ExtensionFunctions.kt

@@ -18,72 +18,118 @@
 
 package kotlin
 
+/** An extension function that takes 0 arguments. */
 public trait ExtensionFunction0<in T, out R> {
+    /** Invokes the function. */
     public fun T.invoke(): R
 }
+/** An extension function that takes 1 argument. */
 public trait ExtensionFunction1<in T, in P1, out R> {
+    /** Invokes the function with the specified argument. */
     public fun T.invoke(p1: P1): R
 }
+/** An extension function that takes 2 arguments. */
 public trait ExtensionFunction2<in T, in P1, in P2, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2): R
 }
+/** An extension function that takes 3 arguments. */
 public trait ExtensionFunction3<in T, in P1, in P2, in P3, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3): R
 }
+/** An extension function that takes 4 arguments. */
 public trait ExtensionFunction4<in T, in P1, in P2, in P3, in P4, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4): R
 }
+/** An extension function that takes 5 arguments. */
 public trait ExtensionFunction5<in T, in P1, in P2, in P3, in P4, in P5, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5): R
 }
+/** An extension function that takes 6 arguments. */
 public trait ExtensionFunction6<in T, in P1, in P2, in P3, in P4, in P5, in P6, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6): R
 }
+/** An extension function that takes 7 arguments. */
 public trait ExtensionFunction7<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7): R
 }
+/** An extension function that takes 8 arguments. */
 public trait ExtensionFunction8<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8): R
 }
+/** An extension function that takes 9 arguments. */
 public trait ExtensionFunction9<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9): R
 }
+/** An extension function that takes 10 arguments. */
 public trait ExtensionFunction10<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10): R
 }
+/** An extension function that takes 11 arguments. */
 public trait ExtensionFunction11<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11): R
 }
+/** An extension function that takes 12 arguments. */
 public trait ExtensionFunction12<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12): R
 }
+/** An extension function that takes 13 arguments. */
 public trait ExtensionFunction13<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13): R
 }
+/** An extension function that takes 14 arguments. */
 public trait ExtensionFunction14<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14): R
 }
+/** An extension function that takes 15 arguments. */
 public trait ExtensionFunction15<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15): R
 }
+/** An extension function that takes 16 arguments. */
 public trait ExtensionFunction16<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16): R
 }
+/** An extension function that takes 17 arguments. */
 public trait ExtensionFunction17<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17): R
 }
+/** An extension function that takes 18 arguments. */
 public trait ExtensionFunction18<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18): R
 }
+/** An extension function that takes 19 arguments. */
 public trait ExtensionFunction19<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19): R
 }
+/** An extension function that takes 20 arguments. */
 public trait ExtensionFunction20<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20): R
 }
+/** An extension function that takes 21 arguments. */
 public trait ExtensionFunction21<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, in P21, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20, p21: P21): R
 }
+/** An extension function that takes 22 arguments. */
 public trait ExtensionFunction22<in T, in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, in P21, in P22, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun T.invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20, p21: P21, p22: P22): R
 }

core/builtins/src/kotlin/FloatingPointConstants.kt

@@ -16,8 +16,22 @@
 
 package kotlin
 
+/**
+ * Holder for special values of floating point types.
+ */
 public trait FloatingPointConstants<T> {
+    /**
+     * A constant holding the positive infinity value.
+     */
     public val POSITIVE_INFINITY: T
+
+    /**
+     * A constant holding the negative infinity value.
+     */
     public val NEGATIVE_INFINITY: T
+
+    /**
+     * A constant holding the "not a number" value.
+     */
     public val NaN: T
 }

core/builtins/src/kotlin/Functions.kt

@@ -18,72 +18,118 @@
 
 package kotlin
 
+/** A function that takes 0 arguments. */
 public trait Function0<out R> {
+    /** Invokes the function. */
     public fun invoke(): R
 }
+/** A function that takes 1 argument. */
 public trait Function1<in P1, out R> {
+    /** Invokes the function with the specified argument. */
     public fun invoke(p1: P1): R
 }
+/** A function that takes 2 arguments. */
 public trait Function2<in P1, in P2, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2): R
 }
+/** A function that takes 3 arguments. */
 public trait Function3<in P1, in P2, in P3, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3): R
 }
+/** A function that takes 4 arguments. */
 public trait Function4<in P1, in P2, in P3, in P4, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4): R
 }
+/** A function that takes 5 arguments. */
 public trait Function5<in P1, in P2, in P3, in P4, in P5, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5): R
 }
+/** A function that takes 6 arguments. */
 public trait Function6<in P1, in P2, in P3, in P4, in P5, in P6, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6): R
 }
+/** A function that takes 7 arguments. */
 public trait Function7<in P1, in P2, in P3, in P4, in P5, in P6, in P7, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7): R
 }
+/** A function that takes 8 arguments. */
 public trait Function8<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8): R
 }
+/** A function that takes 9 arguments. */
 public trait Function9<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9): R
 }
+/** A function that takes 10 arguments. */
 public trait Function10<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10): R
 }
+/** A function that takes 11 arguments. */
 public trait Function11<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11): R
 }
+/** A function that takes 12 arguments. */
 public trait Function12<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12): R
 }
+/** A function that takes 13 arguments. */
 public trait Function13<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13): R
 }
+/** A function that takes 14 arguments. */
 public trait Function14<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14): R
 }
+/** A function that takes 15 arguments. */
 public trait Function15<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15): R
 }
+/** A function that takes 16 arguments. */
 public trait Function16<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16): R
 }
+/** A function that takes 17 arguments. */
 public trait Function17<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17): R
 }
+/** A function that takes 18 arguments. */
 public trait Function18<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18): R
 }
+/** A function that takes 19 arguments. */
 public trait Function19<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19): R
 }
+/** A function that takes 20 arguments. */
 public trait Function20<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20): R
 }
+/** A function that takes 21 arguments. */
 public trait Function21<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, in P21, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20, p21: P21): R
 }
+/** A function that takes 22 arguments. */
 public trait Function22<in P1, in P2, in P3, in P4, in P5, in P6, in P7, in P8, in P9, in P10, in P11, in P12, in P13, in P14, in P15, in P16, in P17, in P18, in P19, in P20, in P21, in P22, out R> {
+    /** Invokes the function with the specified arguments. */
     public fun invoke(p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6, p7: P7, p8: P8, p9: P9, p10: P10, p11: P11, p12: P12, p13: P13, p14: P14, p15: P15, p16: P16, p17: P17, p18: P18, p19: P19, p20: P20, p21: P21, p22: P22): R
 }

core/builtins/src/kotlin/Inline.kt

@@ -27,6 +27,9 @@ public annotation class noinline
  * calling functions. Inline functions can use reified type parameters, and lambdas passed to inline
  * functions can contain non-local returns.
  * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/inline-functions.html) for more information.
+ *
+ * @property strategy the [InlineStrategy] to use for inlining this function.
+ *
  * @see noinline
  * @see inlineOptions
  */
@@ -55,6 +58,8 @@ public enum class InlineStrategy {
  * receiving function are allowed to use non-local control flow statements. Lambdas which are called from
  * a different execution context (for example, from an object contained in the receiving function)
  * are restricted to local control flow statements.
+ *
+ * @property value the inlining options selected for the annotated function parameter.
  */
 public annotation class inlineOptions(vararg val value: InlineOption)
 

core/builtins/src/kotlin/Iterators.kt

@@ -18,7 +18,7 @@
 
 package kotlin
 
-/** An iterator over a sequence of values of type Byte. */
+/** An iterator over a sequence of values of type `Byte`. */
 public abstract class ByteIterator : Iterator<Byte> {
     override final fun next() = nextByte()
 
@@ -26,7 +26,7 @@ public abstract class ByteIterator : Iterator<Byte> {
     public abstract fun nextByte(): Byte
 }
 
-/** An iterator over a sequence of values of type Char. */
+/** An iterator over a sequence of values of type `Char`. */
 public abstract class CharIterator : Iterator<Char> {
     override final fun next() = nextChar()
 
@@ -34,7 +34,7 @@ public abstract class CharIterator : Iterator<Char> {
     public abstract fun nextChar(): Char
 }
 
-/** An iterator over a sequence of values of type Short. */
+/** An iterator over a sequence of values of type `Short`. */
 public abstract class ShortIterator : Iterator<Short> {
     override final fun next() = nextShort()
 
@@ -42,7 +42,7 @@ public abstract class ShortIterator : Iterator<Short> {
     public abstract fun nextShort(): Short
 }
 
-/** An iterator over a sequence of values of type Int. */
+/** An iterator over a sequence of values of type `Int`. */
 public abstract class IntIterator : Iterator<Int> {
     override final fun next() = nextInt()
 
@@ -50,7 +50,7 @@ public abstract class IntIterator : Iterator<Int> {
     public abstract fun nextInt(): Int
 }
 
-/** An iterator over a sequence of values of type Long. */
+/** An iterator over a sequence of values of type `Long`. */
 public abstract class LongIterator : Iterator<Long> {
     override final fun next() = nextLong()
 
@@ -58,7 +58,7 @@ public abstract class LongIterator : Iterator<Long> {
     public abstract fun nextLong(): Long
 }
 
-/** An iterator over a sequence of values of type Float. */
+/** An iterator over a sequence of values of type `Float`. */
 public abstract class FloatIterator : Iterator<Float> {
     override final fun next() = nextFloat()
 
@@ -66,7 +66,7 @@ public abstract class FloatIterator : Iterator<Float> {
     public abstract fun nextFloat(): Float
 }
 
-/** An iterator over a sequence of values of type Double. */
+/** An iterator over a sequence of values of type `Double`. */
 public abstract class DoubleIterator : Iterator<Double> {
     override final fun next() = nextDouble()
 
@@ -74,7 +74,7 @@ public abstract class DoubleIterator : Iterator<Double> {
     public abstract fun nextDouble(): Double
 }
 
-/** An iterator over a sequence of values of type Boolean. */
+/** An iterator over a sequence of values of type `Boolean`. */
 public abstract class BooleanIterator : Iterator<Boolean> {
     override final fun next() = nextBoolean()
 

core/builtins/src/kotlin/ProgressionIterators.kt

@@ -20,7 +20,10 @@ package kotlin
 
 import kotlin.internal.getProgressionFinalElement
 
-/** An iterator over a progression of values of type Byte. */
+/**
+ * An iterator over a progression of values of type `Byte`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class ByteProgressionIterator(start: Byte, end: Byte, val increment: Int) : ByteIterator() {
     private var next = start.toInt()
     private val finalElement: Byte = getProgressionFinalElement(start.toInt(), end.toInt(), increment).toByte()
@@ -40,7 +43,10 @@ class ByteProgressionIterator(start: Byte, end: Byte, val increment: Int) : Byte
     }
 }
 
-/** An iterator over a progression of values of type Char. */
+/**
+ * An iterator over a progression of values of type `Char`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class CharProgressionIterator(start: Char, end: Char, val increment: Int) : CharIterator() {
     private var next = start.toInt()
     private val finalElement: Char = getProgressionFinalElement(start.toInt(), end.toInt(), increment).toChar()
@@ -60,7 +66,10 @@ class CharProgressionIterator(start: Char, end: Char, val increment: Int) : Char
     }
 }
 
-/** An iterator over a progression of values of type Short. */
+/**
+ * An iterator over a progression of values of type `Short`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class ShortProgressionIterator(start: Short, end: Short, val increment: Int) : ShortIterator() {
     private var next = start.toInt()
     private val finalElement: Short = getProgressionFinalElement(start.toInt(), end.toInt(), increment).toShort()
@@ -80,7 +89,10 @@ class ShortProgressionIterator(start: Short, end: Short, val increment: Int) : S
     }
 }
 
-/** An iterator over a progression of values of type Int. */
+/**
+ * An iterator over a progression of values of type `Int`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class IntProgressionIterator(start: Int, end: Int, val increment: Int) : IntIterator() {
     private var next = start
     private val finalElement: Int = getProgressionFinalElement(start, end, increment)
@@ -100,7 +112,10 @@ class IntProgressionIterator(start: Int, end: Int, val increment: Int) : IntIter
     }
 }
 
-/** An iterator over a progression of values of type Long. */
+/**
+ * An iterator over a progression of values of type `Long`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class LongProgressionIterator(start: Long, end: Long, val increment: Long) : LongIterator() {
     private var next = start
     private val finalElement: Long = getProgressionFinalElement(start, end, increment)
@@ -120,7 +135,10 @@ class LongProgressionIterator(start: Long, end: Long, val increment: Long) : Lon
     }
 }
 
-/** An iterator over a progression of values of type Float. */
+/**
+ * An iterator over a progression of values of type `Float`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class FloatProgressionIterator(start: Float, val end: Float, val increment: Float) : FloatIterator() {
     private var next = start
 
@@ -133,7 +151,10 @@ class FloatProgressionIterator(start: Float, val end: Float, val increment: Floa
     }
 }
 
-/** An iterator over a progression of values of type Double. */
+/**
+ * An iterator over a progression of values of type `Double`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class DoubleProgressionIterator(start: Double, val end: Double, val increment: Double) : DoubleIterator() {
     private var next = start
 

core/builtins/src/kotlin/Progressions.kt

@@ -19,7 +19,7 @@
 package kotlin
 
 /**
- * A progression of values of type Byte.
+ * A progression of values of type `Byte`.
  */
 public class ByteProgression(
         override val start: Byte,
@@ -46,7 +46,7 @@ public class ByteProgression(
 }
 
 /**
- * A progression of values of type Char.
+ * A progression of values of type `Char`.
  */
 public class CharProgression(
         override val start: Char,
@@ -73,7 +73,7 @@ public class CharProgression(
 }
 
 /**
- * A progression of values of type Short.
+ * A progression of values of type `Short`.
  */
 public class ShortProgression(
         override val start: Short,
@@ -100,7 +100,7 @@ public class ShortProgression(
 }
 
 /**
- * A progression of values of type Int.
+ * A progression of values of type `Int`.
  */
 public class IntProgression(
         override val start: Int,
@@ -127,7 +127,7 @@ public class IntProgression(
 }
 
 /**
- * A progression of values of type Long.
+ * A progression of values of type `Long`.
  */
 public class LongProgression(
         override val start: Long,
@@ -154,7 +154,7 @@ public class LongProgression(
 }
 
 /**
- * A progression of values of type Float.
+ * A progression of values of type `Float`.
  */
 public class FloatProgression(
         override val start: Float,
@@ -182,7 +182,7 @@ public class FloatProgression(
 }
 
 /**
- * A progression of values of type Double.
+ * A progression of values of type `Double`.
  */
 public class DoubleProgression(
         override val start: Double,

core/builtins/src/kotlin/PropertyMetadata.kt

@@ -26,4 +26,7 @@ public trait PropertyMetadata {
     public val name: String
 }
 
+/**
+ * @suppress
+ */
 public class PropertyMetadataImpl(override val name: String): PropertyMetadata

core/builtins/src/kotlin/Ranges.kt

@@ -19,7 +19,7 @@
 package kotlin
 
 /**
- * A range of values of type Byte.
+ * A range of values of type `Byte`.
  */
 public class ByteRange(override val start: Byte, override val end: Byte) : Range<Byte>, Progression<Byte> {
     override val increment: Int
@@ -45,7 +45,7 @@ public class ByteRange(override val start: Byte, override val end: Byte) : Range
 }
 
 /**
- * A range of values of type Char.
+ * A range of values of type `Char`.
  */
 public class CharRange(override val start: Char, override val end: Char) : Range<Char>, Progression<Char> {
     override val increment: Int
@@ -71,7 +71,7 @@ public class CharRange(override val start: Char, override val end: Char) : Range
 }
 
 /**
- * A range of values of type Short.
+ * A range of values of type `Short`.
  */
 public class ShortRange(override val start: Short, override val end: Short) : Range<Short>, Progression<Short> {
     override val increment: Int
@@ -97,7 +97,7 @@ public class ShortRange(override val start: Short, override val end: Short) : Ra
 }
 
 /**
- * A range of values of type Int.
+ * A range of values of type `Int`.
  */
 public class IntRange(override val start: Int, override val end: Int) : Range<Int>, Progression<Int> {
     override val increment: Int
@@ -123,7 +123,7 @@ public class IntRange(override val start: Int, override val end: Int) : Range<In
 }
 
 /**
- * A range of values of type Long.
+ * A range of values of type `Long`.
  */
 public class LongRange(override val start: Long, override val end: Long) : Range<Long>, Progression<Long> {
     override val increment: Long
@@ -149,7 +149,7 @@ public class LongRange(override val start: Long, override val end: Long) : Range
 }
 
 /**
- * A range of values of type Float.
+ * A range of values of type `Float`.
  */
 public class FloatRange(override val start: Float, override val end: Float) : Range<Float>, Progression<Float> {
     override val increment: Float
@@ -175,7 +175,7 @@ public class FloatRange(override val start: Float, override val end: Float) : Ra
 }
 
 /**
- * A range of values of type Double.
+ * A range of values of type `Double`.
  */
 public class DoubleRange(override val start: Double, override val end: Double) : Range<Double>, Progression<Double> {
     override val increment: Double

core/builtins/src/kotlin/Unit.kt

@@ -16,6 +16,9 @@
 
 package kotlin
 
+/**
+ * The type with only one value: the Unit object. This type corresponds to the `void` type in Java.
+ */
 public object Unit {
     override fun toString() = "kotlin.Unit"
 }

generators/src/org/jetbrains/kotlin/generators/builtins/arrays.kt

@@ -29,7 +29,7 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             val s = kind.capitalized
             val defaultValue = when(kind) { PrimitiveType.BOOLEAN -> "false"; else -> "zero" }
             out.println("/**")
-            out.println(" * An array of ${typeLower}s. When targeting the JVM, instances of this class are represented as ${typeLower}[].")
+            out.println(" * An array of ${typeLower}s. When targeting the JVM, instances of this class are represented as `${typeLower}[]`.")
             out.println(" * @constructor Creates a new array of the specified [size], with all elements initialized to ${defaultValue}.")
             out.println(" */")
             out.println("public class ${s}Array(size: Int) : Cloneable {")

generators/src/org/jetbrains/kotlin/generators/builtins/functions.kt

@@ -24,14 +24,15 @@ val MAX_PARAM_COUNT = 22
 
 enum class FunctionKind(
         private val classNamePrefix: String,
+        val docPrefix: String?,
         val hasReceiverParameter: Boolean,
         private val superClassNamePrefix: String?
 ) {
-    FUNCTION : FunctionKind("Function", false, null)
+    FUNCTION : FunctionKind("Function", "A function", false, null)
-    EXTENSION_FUNCTION : FunctionKind("ExtensionFunction", true, null)
+    EXTENSION_FUNCTION : FunctionKind("ExtensionFunction", "An extension function", true, null)
-    K_FUNCTION : FunctionKind("KFunction", false, "Function")
+    K_FUNCTION : FunctionKind("KFunction", null, false, "Function")
-    K_MEMBER_FUNCTION : FunctionKind("KMemberFunction", true, "ExtensionFunction")
+    K_MEMBER_FUNCTION : FunctionKind("KMemberFunction", null, true, "ExtensionFunction")
-    K_EXTENSION_FUNCTION : FunctionKind("KExtensionFunction", true, "ExtensionFunction")
+    K_EXTENSION_FUNCTION : FunctionKind("KExtensionFunction", null, true, "ExtensionFunction")
 
     fun getFileName() = (if (isReflection()) "reflect/" else "") + classNamePrefix + "s.kt"
     fun getClassName(i: Int) = classNamePrefix + i
@@ -62,6 +63,7 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
 
     override fun generateBody() {
         for (i in 0..MAX_PARAM_COUNT) {
+            generateDocumentation(kind.docPrefix, i)
             out.print("public trait " + kind.getClassName(i))
             generateTypeParameters(i, true)
             generateSuperClass(i)
@@ -69,6 +71,12 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
         }
     }
 
+    fun generateDocumentation(docPrefix: String?, i: Int) {
+        if (docPrefix == null) return
+        val suffix = if (i == 1) "" else "s"
+        out.println("/** $docPrefix that takes $i argument${suffix}. */")
+    }
+
     fun generateSuperClass(i: Int) {
         val superClass = kind.getSuperClassName(i)
         if (superClass != null) {
@@ -89,6 +97,12 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
     }
 
     fun generateInvokeSignature(i: Int) {
+        if (i == 0) {
+            out.println("    /** Invokes the function. */")
+        } else {
+            val suffix = if (i == 1) "" else "s"
+            out.println("    /** Invokes the function with the specified argument${suffix}. */")
+        }
         out.print("    public fun ${if (kind.hasReceiverParameter) "T." else ""}invoke(")
         for (j in 1..i) {
             out.print("p$j: P$j")

generators/src/org/jetbrains/kotlin/generators/builtins/iterators.kt

@@ -24,7 +24,7 @@ class GenerateIterators(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     override fun generateBody() {
         for (kind in PrimitiveType.values()) {
             val s = kind.capitalized
-            out.println("/** An iterator over a sequence of values of type $s. */")
+            out.println("/** An iterator over a sequence of values of type `$s`. */")
             out.println("public abstract class ${s}Iterator : Iterator<$s> {"   )
             out.println("    override final fun next() = next$s()")
             out.println()

generators/src/org/jetbrains/kotlin/generators/builtins/primitives.kt

@@ -21,10 +21,26 @@ import org.jetbrains.kotlin.generators.builtins.generateBuiltIns.BuiltInsSourceG
 import java.io.PrintWriter
 
 class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
-    private val binaryOperators: List<String> = listOf("plus", "minus", "times", "div", "mod")
+    private val binaryOperators: Map<String, String> = mapOf(
-    private val unaryOperators: List<String> = listOf("inc", "dec", "plus", "minus")
+            "plus" to "Adds the other value to this value.",
-    private val shiftOperators: List<String> = listOf("shl", "shr", "ushr")
+            "minus" to "Subtracts the other value from this value.",
-    private val bitwiseOperators: List<String> = listOf("and", "or", "xor")
+            "times" to "Multiplies this value by the other value.",
+            "div" to "Divides this value by the other value.",
+            "mod" to "Calculates the remainder of dividing this value by the other value."
+    )
+    private val unaryOperators: Map<String, String> = mapOf(
+            "inc" to "Increments this value.",
+            "dec" to "Decrements this value.",
+            "plus" to "Returns this value.",
+            "minus" to "Returns the negative of this value.")
+    private val shiftOperators: Map<String, String> = mapOf(
+            "shl" to "Shifts this value left by [bits].",
+            "shr" to "Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit.",
+            "ushr" to "Shifts this value right by [bits], filling the leftmost bits with zeros.")
+    private val bitwiseOperators: Map<String, String> = mapOf(
+            "and" to "Performs a bitwise AND operation between the two values.",
+            "or" to "Performs a bitwise OR operation between the two values.",
+            "xor" to "Performs a bitwise XOR operation between the two values.")
     private val typeDescriptions: Map<PrimitiveType, String> = hashMapOf(
             PrimitiveType.DOUBLE to "double-precision 64-bit IEEE 754 floating point number",
             PrimitiveType.FLOAT to "single-precision 32-bit IEEE 754 floating point number",
@@ -61,7 +77,7 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
                 generateBitwiseOperators(className)
             }
 
-            generateConversions()
+            generateConversions(kind)
 
             out.println("}\n")
         }
@@ -76,6 +92,17 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
     private fun generateCompareTo(thisKind: PrimitiveType) {
         for (otherKind in PrimitiveType.exceptBoolean) {
+            out.println("/**")
+            if (thisKind == PrimitiveType.CHAR && otherKind != PrimitiveType.CHAR) {
+                out.println(" * Compares the character code of this character with the specified value for order.")
+            } else if (thisKind != PrimitiveType.CHAR && otherKind == PrimitiveType.CHAR) {
+                out.println(" * Compares this value with the character code of the specified character for order.")
+            } else {
+                out.println(" * Compares this value with the specified value for order.")
+            }
+            out.println(" * Returns zero if this value is equal to the specified other value, a negative number if its less than other, ")
+            out.println(" * or a positive number if its greater than other.")
+            out.println(" */")
             out.print("    public ")
             if (otherKind == thisKind) out.print("override ")
             out.println("fun compareTo(other: ${otherKind.capitalized}): Int")
@@ -84,17 +111,18 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     }
 
     private fun generateBinaryOperators(thisKind: PrimitiveType) {
-        for (name in binaryOperators) {
+        for ((name, doc) in binaryOperators) {
-            generateOperator(name, thisKind)
+            generateOperator(name, doc, thisKind)
         }
     }
 
-    private fun generateOperator(name: String, thisKind: PrimitiveType) {
+    private fun generateOperator(name: String, doc: String, thisKind: PrimitiveType) {
         for (otherKind in PrimitiveType.exceptBoolean) {
             if (thisKind == PrimitiveType.CHAR && otherKind == PrimitiveType.CHAR && name != "minus") {
                 continue
             }
             val returnType = getOperatorReturnType(thisKind, otherKind)
+            out.println("    /** $doc */")
             out.println("    public fun $name(other: ${otherKind.capitalized}): $returnType")
         }
         out.println()
@@ -102,10 +130,12 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
     private fun generateRangeTo(thisKind: PrimitiveType) {
         if (thisKind == PrimitiveType.CHAR) {
+            out.println("     /** Creates a range from this value to the specified [other] value. */")
             out.println("    public fun rangeTo(other: Char): CharRange")
         } else {
             for (otherKind in PrimitiveType.exceptBoolean) {
                 val returnType = if (otherKind.ordinal() > thisKind.ordinal()) otherKind else thisKind
+                out.println("     /** Creates a range from this value to the specified [other] value. */")
                 out.println("    public fun rangeTo(other: ${otherKind.capitalized}): ${returnType.capitalized}Range")
             }
         }
@@ -114,28 +144,35 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     }
 
     private fun generateUnaryOperators(kind: PrimitiveType) {
-        for (name in unaryOperators) {
+        for ((name, doc) in unaryOperators) {
             val returnType = if (kind in listOf(PrimitiveType.SHORT, PrimitiveType.BYTE, PrimitiveType.CHAR) &&
                                  name in listOf("plus", "minus")) "Int" else kind.capitalized
+            out.println("    /** $doc */")
             out.println("    public fun $name(): $returnType")
         }
         out.println()
     }
 
     private fun generateBitwiseOperators(className: String) {
-        for (name in shiftOperators) {
+        for ((name, doc) in shiftOperators) {
+            out.println("    /** $doc */")
             out.println("    public fun $name(bits: Int): $className")
         }
-        for (name in bitwiseOperators) {
+        for ((name, doc) in bitwiseOperators) {
+            out.println("    /** $doc */")
             out.println("    public fun $name(other: $className): $className")
         }
+        out.println("    /** Inverts the bits in this value/ */")
         out.println("    public fun inv(): $className")
         out.println()
     }
 
-    private fun generateConversions() {
+    private fun generateConversions(kind: PrimitiveType) {
         for (otherKind in PrimitiveType.exceptBoolean) {
             val name = otherKind.capitalized
+            if (kind == PrimitiveType.CHAR) {  // Char is not a Number and does not inherit Number's javadocs
+                out.println("    /** Returns the value of this character as a `$name`. */")
+            }
             out.println("    public override fun to$name(): $name")
         }
     }

generators/src/org/jetbrains/kotlin/generators/builtins/progressionIterators.kt

@@ -31,7 +31,10 @@ fun integerProgressionIterator(kind: ProgressionKind): String {
         else -> "" to ""
     }
 
-    return """/** An iterator over a progression of values of type $t. */
+    return """/**
+ * An iterator over a progression of values of type `$t`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class ${t}ProgressionIterator(start: $t, end: $t, val increment: $incrementType) : ${t}Iterator() {
     private var next = start$toInt
     private val finalElement: $t = getProgressionFinalElement(start$toInt, end$toInt, increment)$toType
@@ -55,7 +58,10 @@ class ${t}ProgressionIterator(start: $t, end: $t, val increment: $incrementType)
 fun floatingPointProgressionIterator(kind: ProgressionKind): String {
     val t = kind.capitalized
 
-    return """/** An iterator over a progression of values of type $t. */
+    return """/**
+ * An iterator over a progression of values of type `$t`.
+ * @property increment the number by which the value is incremented on each step.
+ */
 class ${t}ProgressionIterator(start: $t, val end: $t, val increment: $t) : ${t}Iterator() {
     private var next = start
 

generators/src/org/jetbrains/kotlin/generators/builtins/progressions.kt

@@ -66,7 +66,7 @@ class GenerateProgressions(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
             out.println(
 """/**
- * A progression of values of type $t.
+ * A progression of values of type `$t`.
  */
 public class $progression(
         override val start: $t,

generators/src/org/jetbrains/kotlin/generators/builtins/ranges.kt

@@ -64,7 +64,7 @@ class GenerateRanges(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
             out.println(
 """/**
- * A range of values of type $t.
+ * A range of values of type `$t`.
  */
 public class $range(override val start: $t, override val end: $t) : Range<$t>, Progression<$t> {
     override val increment: $incrementType

libraries/stdlib/src/generated/_DownTo.kt

@@ -6,198 +6,443 @@ package kotlin
 //
 
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Byte): ByteProgression {
     return ByteProgression(this, to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Char): CharProgression {
     return CharProgression(this.toChar(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Short): ShortProgression {
     return ShortProgression(this.toShort(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Int): IntProgression {
     return IntProgression(this.toInt(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Long): LongProgression {
     return LongProgression(this.toLong(), to, -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Float): FloatProgression {
     return FloatProgression(this.toFloat(), to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Byte.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Byte): CharProgression {
     return CharProgression(this, to.toChar(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Char): CharProgression {
     return CharProgression(this, to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Short): ShortProgression {
     return ShortProgression(this.toShort(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Int): IntProgression {
     return IntProgression(this.toInt(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Long): LongProgression {
     return LongProgression(this.toLong(), to, -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Float): FloatProgression {
     return FloatProgression(this.toFloat(), to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Char.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Byte): ShortProgression {
     return ShortProgression(this, to.toShort(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Char): ShortProgression {
     return ShortProgression(this, to.toShort(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Short): ShortProgression {
     return ShortProgression(this, to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Int): IntProgression {
     return IntProgression(this.toInt(), to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Long): LongProgression {
     return LongProgression(this.toLong(), to, -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Float): FloatProgression {
     return FloatProgression(this.toFloat(), to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Short.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Byte): IntProgression {
     return IntProgression(this, to.toInt(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Char): IntProgression {
     return IntProgression(this, to.toInt(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Short): IntProgression {
     return IntProgression(this, to.toInt(), -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Int): IntProgression {
     return IntProgression(this, to, -1)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Long): LongProgression {
     return LongProgression(this.toLong(), to, -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Float): FloatProgression {
     return FloatProgression(this.toFloat(), to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Int.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Byte): LongProgression {
     return LongProgression(this, to.toLong(), -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Char): LongProgression {
     return LongProgression(this, to.toLong(), -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Short): LongProgression {
     return LongProgression(this, to.toLong(), -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Int): LongProgression {
     return LongProgression(this, to.toLong(), -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Long): LongProgression {
     return LongProgression(this, to, -1.toLong())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Float): FloatProgression {
     return FloatProgression(this.toFloat(), to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Long.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Byte): FloatProgression {
     return FloatProgression(this, to.toFloat(), -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Char): FloatProgression {
     return FloatProgression(this, to.toFloat(), -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Short): FloatProgression {
     return FloatProgression(this, to.toFloat(), -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Int): FloatProgression {
     return FloatProgression(this, to.toFloat(), -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Long): FloatProgression {
     return FloatProgression(this, to.toFloat(), -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Float): FloatProgression {
     return FloatProgression(this, to, -1.toFloat())
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Float.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this.toDouble(), to, -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Byte): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Char): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Short): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Int): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Long): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Float): DoubleProgression {
     return DoubleProgression(this, to.toDouble(), -1.0)
 }
 
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun Double.downTo(to: Double): DoubleProgression {
     return DoubleProgression(this, to, -1.0)
 }

libraries/stdlib/src/generated/_Elements.kt

@@ -700,7 +700,7 @@ public fun String.first(): Char {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun <T> Array<out T>.first(predicate: (T) -> Boolean): T {
@@ -709,7 +709,7 @@ public inline fun <T> Array<out T>.first(predicate: (T) -> Boolean): T {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun BooleanArray.first(predicate: (Boolean) -> Boolean): Boolean {
@@ -718,7 +718,7 @@ public inline fun BooleanArray.first(predicate: (Boolean) -> Boolean): Boolean {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun ByteArray.first(predicate: (Byte) -> Boolean): Byte {
@@ -727,7 +727,7 @@ public inline fun ByteArray.first(predicate: (Byte) -> Boolean): Byte {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun CharArray.first(predicate: (Char) -> Boolean): Char {
@@ -736,7 +736,7 @@ public inline fun CharArray.first(predicate: (Char) -> Boolean): Char {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun DoubleArray.first(predicate: (Double) -> Boolean): Double {
@@ -745,7 +745,7 @@ public inline fun DoubleArray.first(predicate: (Double) -> Boolean): Double {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun FloatArray.first(predicate: (Float) -> Boolean): Float {
@@ -754,7 +754,7 @@ public inline fun FloatArray.first(predicate: (Float) -> Boolean): Float {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun IntArray.first(predicate: (Int) -> Boolean): Int {
@@ -763,7 +763,7 @@ public inline fun IntArray.first(predicate: (Int) -> Boolean): Int {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun LongArray.first(predicate: (Long) -> Boolean): Long {
@@ -772,7 +772,7 @@ public inline fun LongArray.first(predicate: (Long) -> Boolean): Long {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun ShortArray.first(predicate: (Short) -> Boolean): Short {
@@ -781,7 +781,7 @@ public inline fun ShortArray.first(predicate: (Short) -> Boolean): Short {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun <T> Iterable<T>.first(predicate: (T) -> Boolean): T {
@@ -790,7 +790,7 @@ public inline fun <T> Iterable<T>.first(predicate: (T) -> Boolean): T {
 }
 
 /**
- * "Returns the first element matching the given [predicate].
+ * Returns the first element matching the given [predicate].
  * @throws NoSuchElementException if no such element is found.
  */
 public inline fun <T> Stream<T>.first(predicate: (T) -> Boolean): T {
@@ -925,7 +925,7 @@ public fun String.firstOrNull(): Char? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun <T> Array<out T>.firstOrNull(predicate: (T) -> Boolean): T? {
     for (element in this) if (predicate(element)) return element
@@ -933,7 +933,7 @@ public inline fun <T> Array<out T>.firstOrNull(predicate: (T) -> Boolean): T? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun BooleanArray.firstOrNull(predicate: (Boolean) -> Boolean): Boolean? {
     for (element in this) if (predicate(element)) return element
@@ -941,7 +941,7 @@ public inline fun BooleanArray.firstOrNull(predicate: (Boolean) -> Boolean): Boo
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun ByteArray.firstOrNull(predicate: (Byte) -> Boolean): Byte? {
     for (element in this) if (predicate(element)) return element
@@ -949,7 +949,7 @@ public inline fun ByteArray.firstOrNull(predicate: (Byte) -> Boolean): Byte? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): Char? {
     for (element in this) if (predicate(element)) return element
@@ -957,7 +957,7 @@ public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): Char? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun DoubleArray.firstOrNull(predicate: (Double) -> Boolean): Double? {
     for (element in this) if (predicate(element)) return element
@@ -965,7 +965,7 @@ public inline fun DoubleArray.firstOrNull(predicate: (Double) -> Boolean): Doubl
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun FloatArray.firstOrNull(predicate: (Float) -> Boolean): Float? {
     for (element in this) if (predicate(element)) return element
@@ -973,7 +973,7 @@ public inline fun FloatArray.firstOrNull(predicate: (Float) -> Boolean): Float?
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun IntArray.firstOrNull(predicate: (Int) -> Boolean): Int? {
     for (element in this) if (predicate(element)) return element
@@ -981,7 +981,7 @@ public inline fun IntArray.firstOrNull(predicate: (Int) -> Boolean): Int? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun LongArray.firstOrNull(predicate: (Long) -> Boolean): Long? {
     for (element in this) if (predicate(element)) return element
@@ -989,7 +989,7 @@ public inline fun LongArray.firstOrNull(predicate: (Long) -> Boolean): Long? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun ShortArray.firstOrNull(predicate: (Short) -> Boolean): Short? {
     for (element in this) if (predicate(element)) return element
@@ -997,7 +997,7 @@ public inline fun ShortArray.firstOrNull(predicate: (Short) -> Boolean): Short?
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun <T> Iterable<T>.firstOrNull(predicate: (T) -> Boolean): T? {
     for (element in this) if (predicate(element)) return element
@@ -1005,7 +1005,7 @@ public inline fun <T> Iterable<T>.firstOrNull(predicate: (T) -> Boolean): T? {
 }
 
 /**
- * Returns first element matching the given [predicate], or `null` if element was not found
+ * Returns the first element matching the given [predicate], or `null` if element was not found
  */
 public inline fun <T> Stream<T>.firstOrNull(predicate: (T) -> Boolean): T? {
     for (element in this) if (predicate(element)) return element
@@ -1013,7 +1013,7 @@ public inline fun <T> Stream<T>.firstOrNull(predicate: (T) -> Boolean): T? {
 }
 
 /**
- * Returns first character matching the given [predicate], or `null` if character was not found
+ * Returns the first character matching the given [predicate], or `null` if character was not found
  */
 public inline fun String.firstOrNull(predicate: (Char) -> Boolean): Char? {
     for (element in this) if (predicate(element)) return element

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

@@ -1,5 +1,9 @@
 package kotlin
 
+/**
+ * Returns an array with the specified [size], where each element is calculated by calling the specified
+ * [init] function. The `init` function returns an array element given its index.
+ */
 public inline fun <reified T> Array(size: Int, init: (Int) -> T): Array<T> {
     val result = arrayOfNulls<T>(size)
 

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

@@ -75,8 +75,12 @@ public fun ByteArray.toString(charset: String): String = String(this, charset)
  */
 public fun ByteArray.toString(charset: Charset): String = String(this, charset)
 
+/**
+ * Returns an array containing the elements of this collection.
+ */
 [Intrinsic("kotlin.collections.copyToArray")] public fun <reified T> Collection<T>.copyToArray(): Array<T> =
         throw UnsupportedOperationException()
 
 /** Returns the array if it's not null, or an empty array otherwise. */
 public inline fun <reified T> Array<out T>?.orEmpty(): Array<out T> = this ?: array<T>()
+

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

@@ -17,7 +17,10 @@ public fun <T> Enumeration<T>.iterator(): Iterator<T> = object : Iterator<T> {
 public fun <T> Iterator<T>.iterator(): Iterator<T> = this
 
 /**
- * Data class representing a value with an index
+ * Data class representing a value from a collection or sequence, along with its index in that collection or sequence.
+ *
+ * @property value the underlying value.
+ * @property index the index of the value in the collection or sequence.
  */
 public data class IndexedValue<out T>(public val index: Int, public val value: T)
 

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

@@ -64,11 +64,14 @@ public fun hashSetOf<T>(vararg values: T): HashSet<T> = values.toCollection(Hash
 public fun linkedSetOf<T>(vararg values: T): LinkedHashSet<T> = values.toCollection(LinkedHashSet(values.size()))
 
 /**
- * Returns an IntRange of 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
 
+/**
+ * Returns an [IntRange] that starts with zero and ends at the value of this number but does not include it.
+ */
 public val Int.indices: IntRange
     get() = 0..this - 1
 
@@ -92,5 +95,12 @@ public fun <T> List<T>?.orEmpty(): List<T> = this ?: emptyList()
 /** Returns this Set if it's not null and the empty set otherwise. */
 public fun <T> Set<T>?.orEmpty(): Set<T> = this ?: emptySet()
 
+/**
+ * Returns the size of this iterable if it is known, or `null` otherwise.
+ */
 public fun <T> Iterable<T>.collectionSizeOrNull(): Int? = if (this is Collection<*>) size() else null
+
+/**
+ * Returns the size of this iterable if it is known, or the specified [default] value otherwise.
+ */
 public fun <T> Iterable<T>.collectionSizeOrDefault(default: Int): Int = if (this is Collection<*>) size() else default

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

@@ -2,12 +2,27 @@ package kotlin
 
 import java.util.*
 
+/**
+ * A sequence that returns values through its iterator. The values are evaluated lazily, and the sequence
+ * is potentially infinite.
+ *
+ * @param T the type of elements in the sequence.
+ */
 public trait Stream<out T> {
+    /**
+     * Returns an iterator that returns the values from the sequence.
+     */
     public fun iterator(): Iterator<T>
 }
 
+/**
+ * Creates a stream that returns the specified values.
+ */
 public fun <T> streamOf(vararg elements: T): Stream<T> = elements.stream()
 
+/**
+ * Creates a stream that returns all values in the specified [progression].
+ */
 public fun <T> streamOf(progression: Progression<T>): Stream<T> = object : Stream<T> {
     override fun iterator(): Iterator<T> = progression.iterator()
 }
@@ -60,6 +75,10 @@ public class FilteringStream<T>(private val stream: Stream<T>,
     }
 }
 
+/**
+ * A stream which returns the results of applying the given [transformer] function to the values
+ * in the underlying [stream].
+ */
 public class TransformingStream<T, R>(private val stream: Stream<T>, private val transformer: (T) -> R) : Stream<R> {
     override fun iterator(): Iterator<R> = object : Iterator<R> {
         val iterator = stream.iterator()
@@ -72,6 +91,11 @@ public class TransformingStream<T, R>(private val stream: Stream<T>, private val
     }
 }
 
+/**
+ * A stream which returns the results of applying the given [transformer] function to the values
+ * in the underlying [stream], where the transformer function takes the index of the value in the underlying
+ * stream along with the value itself.
+ */
 public class TransformingIndexedStream<T, R>(private val stream: Stream<T>, private val transformer: (Int, T) -> R) : Stream<R> {
     override fun iterator(): Iterator<R> = object : Iterator<R> {
         val iterator = stream.iterator()
@@ -103,6 +127,11 @@ public class IndexingStream<T>(private val stream: Stream<T>) : Stream<IndexedVa
     }
 }
 
+/**
+ * A stream which takes the values from two parallel underlying streams, passes them to the given
+ * [transform] function and returns the values returned by that function. The stream stops returning
+ * values as soon as one of the underlying streams stops returning values.
+ */
 public class MergingStream<T1, T2, V>(private val stream1: Stream<T1>,
                                       private val stream2: Stream<T2>,
                                       private val transform: (T1, T2) -> V
@@ -193,6 +222,10 @@ public class Multistream<T>(private val stream: Stream<Stream<T>>) : Stream<T> {
     }
 }
 
+/**
+ * A stream that returns at most [count] values from the underlying [stream], and stops returning values
+ * as soon as that count is reached.
+ */
 public class TakeStream<T>(private val stream: Stream<T>,
                            private val count: Int
                           ) : Stream<T> {
@@ -218,6 +251,10 @@ public class TakeStream<T>(private val stream: Stream<T>,
     }
 }
 
+/**
+ * A stream that returns values from the underlying [stream] while the [predicate] function returns
+ * `true`, and stops returning values once the function returns `false` for the next element.
+ */
 public class TakeWhileStream<T>(private val stream: Stream<T>,
                                 private val predicate: (T) -> Boolean
                                ) : Stream<T> {
@@ -382,7 +419,7 @@ public class FunctionStream<T : Any>(private val producer: () -> T?) : Stream<T>
 }
 
 /**
- * Returns a stream which invokes the function to calculate the next value on each iteration until the function returns *null*
+ * Returns a stream which invokes the function to calculate the next value on each iteration until the function returns `null`.
  */
 public fun <T : Any> stream(nextFunction: () -> T?): Stream<T> {
     return FunctionStream(nextFunction)
@@ -390,7 +427,7 @@ public fun <T : Any> stream(nextFunction: () -> T?): Stream<T> {
 
 /**
  * Returns a stream which invokes the function to calculate the next value based on the previous one on each iteration
- * until the function returns *null*
+ * until the function returns `null`.
  */
 public /*inline*/ fun <T : Any> stream(initialValue: T, nextFunction: (T) -> T?): Stream<T> =
         stream(nextFunction.toGenerator(initialValue))

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

@@ -54,7 +54,8 @@ public inline fun <T> ReentrantReadWriteLock.write(action: () -> T): T {
 }
 
 /**
- * Executes the given [action] and await for CountDownLatch
+ * Executes the given [operation] and awaits for CountDownLatch.
+ *
  * @return the return value of the action.
  */
 public fun <T> Int.latch(operation: CountDownLatch.() -> T): T {

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

@@ -2,36 +2,65 @@ package kotlin.concurrent
 
 import java.util.concurrent.*
 
+/**
+ * Returns the current thread.
+ */
 public val currentThread: Thread
     get() = Thread.currentThread()
 
+/**
+ * Exposes the name of this thread as a property.
+ */
 public var Thread.name: String
     get() = getName()
     set(value) {
         setName(value)
     }
 
+/**
+ * Exposes the daemon flag of this thread as a property.
+ * The Java Virtual Machine exits when the only threads running are all daemon threads.
+ */
 public var Thread.daemon: Boolean
     get() = isDaemon()
     set(value) {
         setDaemon(value)
     }
 
+/**
+ * Exposes the alive state of this thread as a property.
+ */
 public val Thread.alive: Boolean
     get() = isAlive()
 
+/**
+ * Exposes the priority of this thread as a property.
+ */
 public var Thread.priority: Int
     get() = getPriority()
     set(value) {
         setPriority(value)
     }
 
+/**
+ * Exposes the context class loader of this thread as a property.
+ */
 public var Thread.contextClassLoader: ClassLoader?
     get() = getContextClassLoader()
     set(value) {
         setContextClassLoader(value)
     }
 
+/**
+ * Creates a thread that runs the specified [block] of code.\
+ *
+ * @param start if `true`, the thread is immediately started.
+ * @param daemon if `true`, the thread is created as a daemon thread. The Java Virtual Machine exits when
+ * the only threads running are all daemon threads.
+ * @param contextClassLoader the class loader to use for loading classes and resources in this thread.
+ * @param name the name of the thread.
+ * @param priority the priority of the thread.
+ */
 public fun thread(start: Boolean = true, daemon: Boolean = false, contextClassLoader: ClassLoader? = null, name: String? = null, priority: Int = -1, block: () -> Unit): Thread {
     val thread = object : Thread() {
         public override fun run() {
@@ -53,15 +82,15 @@ public fun thread(start: Boolean = true, daemon: Boolean = false, contextClassLo
 
 /**
  * Allows you to use the executor as a function to
- * execute the given block on the [[Executor]].
+ * execute the given block on the [Executor].
  */
 public fun Executor.invoke(action: () -> Unit) {
     execute(action)
 }
 
 /**
- * Allows you to use the executor as a function to
+ * Allows you to use the executor service as a function to
- * execute the given block on the [[Executor]].
+ * execute the given block on the [ExecutorService].
  */
 public fun <T> ExecutorService.invoke(action: () -> T): Future<T> {
     return submit(action)

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

@@ -4,66 +4,123 @@ import java.util.Timer
 import java.util.TimerTask
 import java.util.Date
 
+/**
+ * Schedules an [action] to be executed after the specified [delay] (expressed in milliseconds).
+ */
 public fun Timer.schedule(delay: Long, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     schedule(task, delay)
     return task
 }
 
+/**
+ * Schedules an [action] to be executed at the specified [time].
+ */
 public fun Timer.schedule(time: Date, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     schedule(task, time)
     return task
 }
 
+/**
+ * Schedules an [action] to be executed periodically, starting after the specified [delay] (expressed
+ * in milliseconds) and with the interval of [period] milliseconds between the end of the previous task
+ * and the start of the next one.
+ */
 public fun Timer.schedule(delay: Long, period: Long, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     schedule(task, delay, period)
     return task
 }
 
+/**
+ * Schedules an [action] to be executed periodically, starting at the specified [time] and with the
+ * interval of [period] milliseconds between the end of the previous task and the start of the next one.
+ */
 public fun Timer.schedule(time: Date, period: Long, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     schedule(task, time, period)
     return task
 }
 
+/**
+ * Schedules an [action] to be executed periodically, starting after the specified [delay] (expressed
+ * in milliseconds) and with the interval of [period] milliseconds between the start of the previous task
+ * and the start of the next one.
+ */
 public fun Timer.scheduleAtFixedRate(delay: Long, period: Long, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     scheduleAtFixedRate(task, delay, period)
     return task
 }
 
+/**
+ * Schedules an [action] to be executed periodically, starting at the specified [time] and with the
+ * interval of [period] milliseconds between the start of the previous task and the start of the next one.
+ */
 public fun Timer.scheduleAtFixedRate(time: Date, period: Long, action: TimerTask.() -> Unit): TimerTask {
     val task = timerTask(action)
     scheduleAtFixedRate(task, time, period)
     return task
 }
 
+/**
+ * Creates a timer that executes the specified [action] periodically, starting after the specified [initialDelay]
+ * (expressed in milliseconds) and with the interval of [period] milliseconds between the end of the previous task
+ * and the start of the next one.
+ *
+ * @param name the name to use for the thread which is running the timer.
+ * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ */
 public fun timer(name: String? = null, daemon: Boolean = false, initialDelay: Long = 0.toLong(), period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
     timer.schedule(initialDelay, period, action)
     return timer
 }
 
+/**
+ * Creates a timer that executes the specified [action] periodically, starting at the specified [startAt] date
+ * and with the interval of [period] milliseconds between the end of the previous task and the start of the next one.
+ *
+ * @param name the name to use for the thread which is running the timer.
+ * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ */
 public fun timer(name: String? = null, daemon: Boolean = false, startAt: Date, period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
     timer.schedule(startAt, period, action)
     return timer
 }
 
+/**
+ * Creates a timer that executes the specified [action] periodically, starting after the specified [initialDelay]
+ * (expressed in milliseconds) and with the interval of [period] milliseconds between the start of the previous task
+ * and the start of the next one.
+ *
+ * @param name the name to use for the thread which is running the timer.
+ * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ */
 public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, initialDelay: Long = 0.toLong(), period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
     timer.scheduleAtFixedRate(initialDelay, period, action)
     return timer
 }
 
+/**
+ * Creates a timer that executes the specified [action] periodically, starting at the specified [startAt] date
+ * and with the interval of [period] milliseconds between the start of the previous task and the start of the next one.
+ *
+ * @param name the name to use for the thread which is running the timer.
+ * @param daemon if true, the thread is started as a daemon thread (the VM will exit when only daemon threads are running)
+ */
 public fun fixedRateTimer(name: String? = null, daemon: Boolean = false, startAt: Date, period: Long, action: TimerTask.() -> Unit): Timer {
     val timer = if (name == null) Timer(daemon) else Timer(name, daemon)
     timer.scheduleAtFixedRate(startAt, period, action)
     return timer
 }
 
+/**
+ * Wraps the specified [action] in a `TimerTask`.
+ */
 public fun timerTask(action: TimerTask.() -> Unit): TimerTask = object : TimerTask() {
     public override fun run() {
         action()

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 the standard output stream. */
 public fun print(message: Any?) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Int) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Long) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Byte) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Short) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Char) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Boolean) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Float) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 public fun print(message: Double) {
     System.out.print(message)
 }
-/** Prints the given message to [System.out] */
+/** Prints the given message to the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 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 the standard output stream. */
 public fun println(message: CharArray) {
     System.out.println(message)
 }
-/** Prints a newline to [System.out] */
+/** Prints a newline to the standard output stream. */
 public fun println() {
     System.out.println()
 }
@@ -137,7 +137,8 @@ private val stdin: BufferedReader = BufferedReader(InputStreamReader(object : In
 }))
 
 /**
- * Reads a line of input from [System.in]
+ * Reads a line of input from the standard input stream.
+ *
  * @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/jvm/BuiltinExtensions.kt

@@ -15,20 +15,56 @@
  */
 package kotlin.jvm
 
+/**
+ * A constant holding the minimum value an `Int` can have, -2^31.
+ */
 public val Int.Default.MIN_VALUE: Int get() = java.lang.Integer.MIN_VALUE
+/**
+ * A constant holding the maximum value an `Int` can have, 2^31-1.
+ */
 public val Int.Default.MAX_VALUE: Int get() = java.lang.Integer.MAX_VALUE
 
+/**
+ * A constant holding the smallest positive nonzero value of type `Double`, 2^-1074.
+ */
 public val Double.Default.MIN_VALUE: Double get() = java.lang.Double.MIN_VALUE
+/**
+ * A constant holding the largest positive finite value of type `Double`, (2-2^-52)*2^1023.
+ */
 public val Double.Default.MAX_VALUE: Double get() = java.lang.Double.MAX_VALUE
 
+/**
+ * A constant holding the smallest positive nonzero value of type `Float`, 2^-149.
+ */
 public val Float.Default.MIN_VALUE: Float get() = java.lang.Float.MIN_VALUE
+/**
+ * * A constant holding the largest positive finite value of type `Float`, (2-2^-23)*2^127.
+ */
 public val Float.Default.MAX_VALUE: Float get() = java.lang.Float.MAX_VALUE
 
+/**
+ * A constant holding the minimum value a `Long` can have, -2^63.
+ */
 public val Long.Default.MIN_VALUE: Long get() = java.lang.Long.MIN_VALUE
+/**
+ * A constant holding the maximum value a `Long` can have, 2^63-1.
+ */
 public val Long.Default.MAX_VALUE: Long get() = java.lang.Long.MAX_VALUE
 
+/**
+ * A constant holding the minimum value a `Short` can have, -2^15.
+ */
 public val Short.Default.MIN_VALUE: Short get() = java.lang.Short.MIN_VALUE
+/**
+ * A constant holding the maximum value a `Short` can have, 2^15-1.
+ */
 public val Short.Default.MAX_VALUE: Short get() = java.lang.Short.MAX_VALUE
 
+/**
+ * A constant holding the minimum value a `Byte` can have, -128.
+ */
 public val Byte.Default.MIN_VALUE: Byte get() = java.lang.Byte.MIN_VALUE
+/**
+ * A constant holding the maximum value a `Byte` can have, 127.
+ */
 public val Byte.Default.MAX_VALUE: Byte get() = java.lang.Byte.MAX_VALUE

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

@@ -21,6 +21,7 @@ package kotlin.platform
  * 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.
+ * @property name the name of the element.
  */
 public annotation class platformName(public val name: String)
 

libraries/stdlib/src/kotlin/test/Test.kt

@@ -89,18 +89,49 @@ public fun fails(block: () -> Unit): Throwable? {
 }
 
 /**
- * A plugin for performing assertions which can reuse JUnit or TestNG
+ * Abstracts the logic for performing assertions. Specific implementations of [Asserter] can use JUnit
+ * or TestNG assertion facilities.
  */
 public trait Asserter {
+    /**
+     * Asserts that the specified value is true.
+     *
+     * @param message the message to report if the assertion fails.
+     */
     public fun assertTrue(message: String, actual: Boolean): Unit
 
+    /**
+     * Asserts that the specified values are equal.
+     *
+     * @param message the message to report if the assertion fails.
+     */
     public fun assertEquals(message: String, expected: Any?, actual: Any?): Unit
 
+    /**
+     * Asserts that the specified values are not equal.
+     *
+     * @param message the message to report if the assertion fails.
+     */
     public fun assertNotEquals(message: String, illegal: Any?, actual: Any?): Unit
 
+    /**
+     * Asserts that the specified value is not null.
+     *
+     * @param message the message to report if the assertion fails.
+     */
     public fun assertNotNull(message: String, actual: Any?): Unit
 
+    /**
+     * Asserts that the specified value is null.
+     *
+     * @param message the message to report if the assertion fails.
+     */
     public fun assertNull(message: String, actual: Any?): Unit
 
+    /**
+     * Fails the current test with the specified message.
+     *
+     * @param message the message to report.
+     */
     public fun fail(message: String): Unit
 }

libraries/stdlib/src/kotlin/test/TestJVM.kt

@@ -26,6 +26,10 @@ public inline fun todo(block: ()-> Any) {
 
 private var _asserter: Asserter? = null
 
+/**
+ * The active implementation of [Asserter]. An implementation of [Asserter] can be provided
+ * using the [Java service loader](http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html) mechanism.
+ */
 public var asserter: Asserter
     get() {
         if (_asserter == null) {
@@ -51,7 +55,7 @@ public var asserter: Asserter
 
 
 /**
- * Default implementation to avoid dependency on JUnit or TestNG
+ * Default [Asserter] implementation to avoid dependency on JUnit or TestNG.
  */
 private class DefaultAsserter() : Asserter {
 

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

@@ -16,37 +16,59 @@
 
 package kotlin
 
+/**
+ * Returns `true` if this character (Unicode code point) is defined in Unicode.
+ */
 public fun Char.isDefined(): Boolean = Character.isDefined(this)
 
+/**
+ * Returns `true` if this character (Unicode code point) is a digit.
+ */
 public fun Char.isDigit(): Boolean = Character.isDigit(this)
 
+/**
+ * Returns `true` if this character is a Unicode high-surrogate code unit (also known as leading-surrogate code unit).
+ */
 public fun Char.isHighSurrogate(): Boolean = Character.isHighSurrogate(this)
 
+/**
+ * Returns `true` if this character (Unicode code point) should be regarded as an ignorable
+ * character in a Java identifier or a Unicode identifier.
+ */
 public fun Char.isIdentifierIgnorable(): Boolean = Character.isIdentifierIgnorable(this)
 
+/**
+ * Returns `true` if this character is an ISO control character.
+ */
 public fun Char.isISOControl(): Boolean = Character.isISOControl(this)
 
+/**
+ * Returns `true` if this  character (Unicode code point) may be part of a Java identifier as other than the first character.
+ */
 public fun Char.isJavaIdentifierPart(): Boolean = Character.isJavaIdentifierPart(this)
 
+/**
+ * Returns `true` if this character is permissible as the first character in a Java identifier.
+ */
 public fun Char.isJavaIdentifierStart(): Boolean = Character.isJavaIdentifierStart(this)
 
+deprecated("Please use Char.isJavaIdentifierStart() instead")
 public fun Char.isJavaLetter(): Boolean = Character.isJavaLetter(this)
 
+deprecated("Please use Char.isJavaIdentifierPart() instead")
 public fun Char.isJavaLetterOrDigit(): Boolean = Character.isJavaLetterOrDigit(this)
 
 /**
- * Returns true if the character is whitespace
+ * Returns `true` if the character is whitespace.
- *
- * @includeFunctionBody ../../test/text/StringTest.kt count
  */
 public fun Char.isWhitespace(): Boolean = Character.isWhitespace(this)
 
 /**
- * Returns true if this character is upper case
+ * Returns `true` if this character is upper case.
  */
 public fun Char.isUpperCase(): Boolean = Character.isUpperCase(this)
 
 /**
- * Returns true if this character is lower case
+ * Returns `true` if this character is lower case.
  */
 public fun Char.isLowerCase(): Boolean = Character.isLowerCase(this)

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

@@ -7,127 +7,363 @@ import java.util.regex.MatchResult
 import java.util.regex.Pattern
 import java.nio.charset.Charset
 
+/**
+ * Returns the index within this string of the last occurrence of the specified substring.
+ */
 public fun String.lastIndexOf(str: String): Int = (this as java.lang.String).lastIndexOf(str)
 
+/**
+ * Returns the index within this string of the last occurrence of the specified character.
+ */
 public fun String.lastIndexOf(ch: Char): Int = (this as java.lang.String).lastIndexOf(ch.toString())
 
+/**
+ * Compares this string to another string, ignoring case considerations.
+ */
 public fun String.equalsIgnoreCase(anotherString: String): Boolean = (this as java.lang.String).equalsIgnoreCase(anotherString)
 
+/**
+ * Returns the hash code of this string.
+ */
 public fun String.hashCode(): Int = (this as java.lang.String).hashCode()
 
+/**
+ * Returns the index within this string of the first occurrence of the specified substring.
+ */
 public fun String.indexOf(str: String): Int = (this as java.lang.String).indexOf(str)
 
+/**
+ * Returns the index within this string of the first occurrence of the specified substring, starting from the specified offset.
+ */
 public fun String.indexOf(str: String, fromIndex: Int): Int = (this as java.lang.String).indexOf(str, fromIndex)
 
+/**
+ * Returns a copy of this string with all occurrences of [oldChar] replaced with [newChar].
+ */
 public fun String.replace(oldChar: Char, newChar: Char): String = (this as java.lang.String).replace(oldChar, newChar)
 
+/**
+ * Returns a new string obtained by replacing each substring of this string that matches the given regular expression
+ * with the given [replacement].
+ */
 public fun String.replaceAll(regex: String, replacement: String): String = (this as java.lang.String).replaceAll(regex, replacement)
 
+/**
+ * Returns a copy of this string with leading and trailing whitespace trimmed.
+ */
 public fun String.trim(): String = (this as java.lang.String).trim()
 
+/**
+ * Returns a copy of this string converted to upper case using the rules of the default locale.
+ */
 public fun String.toUpperCase(): String = (this as java.lang.String).toUpperCase()
 
+/**
+ * Returns a copy of this string converted to lower case using the rules of the default locale.
+ */
 public fun String.toLowerCase(): String = (this as java.lang.String).toLowerCase()
 
+/**
+ * Returns a new character array containing the characters from this string.
+ */
 public fun String.toCharArray(): CharArray = (this as java.lang.String).toCharArray()
 
+/**
+ * Uses this string as a format string and returns a string obtained by substituting the specified arguments,
+ * using the default locale.
+ */
 public fun String.format(vararg args: Any?): String = java.lang.String.format(this, *args)
 
+/**
+ * Uses this string as a format string and returns a string obtained by substituting the specified arguments, using
+ * the specified locale.
+ */
 public fun String.format(locale: Locale, vararg args : Any?) : String = java.lang.String.format(locale, this, *args)
 
+/**
+ * Splits this string around matches of the given regular expression.
+ */
 public fun String.split(regex: String): Array<String> = (this as java.lang.String).split(regex)
 
+/**
+ * Splits this string around occurrences of the specified character.
+ */
 public fun String.split(ch: Char): Array<String> = (this as java.lang.String).split(java.util.regex.Pattern.quote(ch.toString()))
 
+/**
+ * Returns a substring of this string starting with the specified index.
+ */
 public fun String.substring(beginIndex: Int): String = (this as java.lang.String).substring(beginIndex)
 
+/**
+ * Returns the substring of this string starting and ending at the specified indices.
+ */
 public fun String.substring(beginIndex: Int, endIndex: Int): String = (this as java.lang.String).substring(beginIndex, endIndex)
 
+/**
+ * Returns `true` if this string starts with the specified prefix.
+ */
 public fun String.startsWith(prefix: String): Boolean = (this as java.lang.String).startsWith(prefix)
 
+/**
+ * Returns `true` if a subsring of this string starting at the specified offset starts with the specified prefix.
+ */
 public fun String.startsWith(prefix: String, toffset: Int): Boolean = (this as java.lang.String).startsWith(prefix, toffset)
 
+/**
+ * Returns `true` if this string starts with the specified character.
+ */
 public fun String.startsWith(ch: Char): Boolean = (this as java.lang.String).startsWith(ch.toString())
 
+/**
+ * Returns `true` if this string contains the specified sequence of characters as a substring.
+ */
 public fun String.contains(seq: CharSequence): Boolean = (this as java.lang.String).contains(seq)
 
+/**
+ * Returns `true` if this string ends with the specified suffix.
+ */
 public fun String.endsWith(suffix: String): Boolean = (this as java.lang.String).endsWith(suffix)
 
+/**
+ * Returns `true` if this string ends with the specified character.
+ */
 public fun String.endsWith(ch: Char): Boolean = (this as java.lang.String).endsWith(ch.toString())
 
 // "constructors" for String
 
+/**
+ * Converts the data from a portion of the specified array of bytes to characters using the specified character set
+ * and returns the conversion result as a string.
+ *
+ * @param bytes the source array for the conversion.
+ * @param offset the offset in the array of the data to be converted.
+ * @param length the number of bytes to be converted.
+ * @param charsetName the name of the character set to use.
+ */
 public fun String(bytes: ByteArray, offset: Int, length: Int, charsetName: String): String = java.lang.String(bytes, offset, length, charsetName) as String
 
+/**
+ * Converts the data from a portion of the specified array of bytes to characters using the specified character set
+ * and returns the conversion result as a string.
+ *
+ * @param bytes the source array for the conversion.
+ * @param offset the offset in the array of the data to be converted.
+ * @param length the number of bytes to be converted.
+ * @param charset the character set to use.
+ */
 public fun String(bytes: ByteArray, offset: Int, length: Int, charset: Charset): String = java.lang.String(bytes, offset, length, charset) as String
 
+/**
+ * Converts the data from the specified array of bytes to characters using the specified character set
+ * and returns the conversion result as a string.
+ */
 public fun String(bytes: ByteArray, charsetName: String): String = java.lang.String(bytes, charsetName) as String
 
+/**
+ * Converts the data from the specified array of bytes to characters using the specified character set
+ * and returns the conversion result as a string.
+ */
 public fun String(bytes: ByteArray, charset: Charset): String = java.lang.String(bytes, charset) as String
 
-public fun String(bytes: ByteArray, i: Int, i1: Int): String = java.lang.String(bytes, i, i1, Charsets.UTF_8) as String
+/**
+ * Converts the data from a portion of the specified array of bytes to characters using the UTF-8 character set
+ * and returns the conversion result as a string.
+ *
+ * @param bytes the source array for the conversion.
+ * @param offset the offset in the array of the data to be converted.
+ * @param length the number of bytes to be converted.
+ */
+public fun String(bytes: ByteArray, offset: Int, length: Int): String = java.lang.String(bytes, offset, length, Charsets.UTF_8) as String
 
+/**
+ * Converts the data from the specified array of bytes to characters using the UTF-8 character set
+ * and returns the conversion result as a string.
+ */
 public fun String(bytes: ByteArray): String = java.lang.String(bytes, Charsets.UTF_8) as String
 
+/**
+ * Converts the characters in the specified array to a string.
+ */
 public fun String(chars: CharArray): String = java.lang.String(chars) as String
 
+/**
+ * Converts the contents of the specified StringBuffer to a string.
+ */
 public fun String(stringBuffer: java.lang.StringBuffer): String = java.lang.String(stringBuffer) as String
 
+/**
+ * Converts the contents of the specified StringBuilder to a string.
+ */
 public fun String(stringBuilder: java.lang.StringBuilder): String = java.lang.String(stringBuilder) as String
 
+/**
+ * Replaces the first substring of this string that matches the given regular expression with the given replacement.
+ */
 public fun String.replaceFirst(regex: String, replacement: String): String = (this as java.lang.String).replaceFirst(regex, replacement)
 
+/**
+ * Splits this string into at most [limit] chunks around matches of the given regular expression.
+ */
 public fun String.split(regex: String, limit: Int): Array<String> = (this as java.lang.String).split(regex, limit)
 
+/**
+ * Returns the character (Unicode code point) at the specified index.
+ */
 public fun String.codePointAt(index: Int): Int = (this as java.lang.String).codePointAt(index)
 
+/**
+ * Returns the character (Unicode code point) before the specified index.
+ */
 public fun String.codePointBefore(index: Int): Int = (this as java.lang.String).codePointBefore(index)
 
+/**
+ * Returns the number of Unicode code points in the specified text range of this String.
+ */
 public fun String.codePointCount(beginIndex: Int, endIndex: Int): Int = (this as java.lang.String).codePointCount(beginIndex, endIndex)
 
+/**
+ * Compares two strings lexicographically, ignoring case differences.
+ */
 public fun String.compareToIgnoreCase(str: String): Int = (this as java.lang.String).compareToIgnoreCase(str)
 
+/**
+ * Returns a new string obtained by concatenating this string and the specified string.
+ */
 public fun String.concat(str: String): String = (this as java.lang.String).concat(str)
 
+/**
+ * Returns `true` if this string is equal to the contents of the specified CharSequence.
+ */
 public fun String.contentEquals(cs: CharSequence): Boolean = (this as java.lang.String).contentEquals(cs)
 
+/**
+ * Returns `true` if this string is equal to the contents of the specified StringBuffer.
+ */
 public fun String.contentEquals(sb: StringBuffer): Boolean = (this as java.lang.String).contentEquals(sb)
 
+/**
+ * Copies the characters from a substring of this string into the specified character array.
+ * @param srcBegin the start offset (inclusive) of the substring to copy.
+ * @param srcEnd the end offset (exclusive) of the substring to copy.
+ * @param dst the array to copy to.
+ * @param dstBegin the position in the array to copy to.
+ */
 public fun String.getChars(srcBegin: Int, srcEnd: Int, dst: CharArray, dstBegin: Int): Unit = (this as java.lang.String).getChars(srcBegin, srcEnd, dst, dstBegin)
 
+/**
+ * Returns the index within this string of the first occurrence of the specified character.
+ */
 public fun String.indexOf(ch: Char): Int = (this as java.lang.String).indexOf(ch.toString())
 
+/**
+ * Returns the index within this string of the first occurrence of the specified character, starting from the specified offset.
+ */
 public fun String.indexOf(ch: Char, fromIndex: Int): Int = (this as java.lang.String).indexOf(ch.toString(), fromIndex)
 
+/**
+ * Returns a canonical representation for this string object.
+ */
 public fun String.intern(): String = (this as java.lang.String).intern()
 
+/**
+ * Returns `true` if this string is empty (contains no characters).
+ */
 public fun String.isEmpty(): Boolean = (this as java.lang.String).isEmpty()
 
+/**
+ * Returns the index within this string of the last occurrence of the specified character.
+ */
 public fun String.lastIndexOf(ch: Char, fromIndex: Int): Int = (this as java.lang.String).lastIndexOf(ch.toString(), fromIndex)
 
+/**
+ * Returns the index within this string of the last occurrence of the specified character, starting from the specified offset.
+ */
 public fun String.lastIndexOf(str: String, fromIndex: Int): Int = (this as java.lang.String).lastIndexOf(str, fromIndex)
 
+/**
+ * Returns `true` if this string matches the given regular expression.
+ */
 public fun String.matches(regex: String): Boolean = (this as java.lang.String).matches(regex)
 
+/**
+ * Returns the index within this string that is offset from the given [index] by [codePointOffset] code points.
+ */
 public fun String.offsetByCodePoints(index: Int, codePointOffset: Int): Int = (this as java.lang.String).offsetByCodePoints(index, codePointOffset)
 
+/**
+ * Returns `true` if the specified range in this string is equal to the specified range in another string.
+ * @param ignoreCase if `true`, character case is ignored when comparing.
+ * @param toffset the start offset in this string of the substring to compare.
+ * @param other the string against a substring of which the comparison is performed.
+ * @param ooffset the start offset in the other string of the substring to compare.
+ * @param len the length of the substring to compare.
+ */
 public fun String.regionMatches(ignoreCase: Boolean, toffset: Int, other: String, ooffset: Int, len: Int): Boolean = (this as java.lang.String).regionMatches(ignoreCase, toffset, other, ooffset, len)
 
+/**
+ * Returns `true` if the specified range in this string is equal to the specified range in another string.
+ * @param toffset the start offset in this string of the substring to compare.
+ * @param other the string against a substring of which the comparison is performed.
+ * @param ooffset the start offset in the other string of the substring to compare.
+ * @param len the length of the substring to compare.
+ */
 public fun String.regionMatches(toffset: Int, other: String, ooffset: Int, len: Int): Boolean = (this as java.lang.String).regionMatches(toffset, other, ooffset, len)
 
+/**
+ * Returns a new string obtained by replacing all occurrences of the [target] substring in this string
+ * with the specified [replacement] string.
+ */
 public fun String.replace(target: CharSequence, replacement: CharSequence): String = (this as java.lang.String).replace(target, replacement)
 
+/**
+ * Returns a copy of this string converted to lower case using the rules of the specified locale.
+ */
 public fun String.toLowerCase(locale: java.util.Locale): String = (this as java.lang.String).toLowerCase(locale)
 
+/**
+ * Returns a copy of this string converted to upper case using the rules of the specified locale.
+ */
 public fun String.toUpperCase(locale: java.util.Locale): String = (this as java.lang.String).toUpperCase(locale)
 
+/**
+ * Returns `true` if the contents of this string is equal to the word "true", ignoring case, and `false` otherwise.
+ */
 public fun String.toBoolean(): Boolean = java.lang.Boolean.parseBoolean(this)
+
+/**
+ * Parses the string as a [Short] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
 public fun String.toShort(): Short = java.lang.Short.parseShort(this)
+
+/**
+ * Parses the string as an [Int] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
 public fun String.toInt(): Int = java.lang.Integer.parseInt(this)
+
+/**
+ * Parses the string as a [Long] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
 public fun String.toLong(): Long = java.lang.Long.parseLong(this)
+
+/**
+ * Parses the string as a [Float] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
 public fun String.toFloat(): Float = java.lang.Float.parseFloat(this)
+
+/**
+ * Parses the string as a [Double] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
 public fun String.toDouble(): Double = java.lang.Double.parseDouble(this)
 
+/**
+ * Returns the list of all characters in this string.
+ */
 public fun String.toCharList(): List<Char> = toCharArray().toList()
 
 /**
@@ -138,7 +374,14 @@ public fun String.toCharList(): List<Char> = toCharArray().toList()
  */
 public fun CharSequence.get(start: Int, end: Int): CharSequence = subSequence(start, end)
 
+/**
+ * Encodes the contents of this string using the specified character set and returns the resulting byte array.
+ */
 public fun String.toByteArray(charset: String): ByteArray = (this as java.lang.String).getBytes(charset)
+
+/**
+ * Encodes the contents of this string using the specified character set and returns the resulting byte array.
+ */
 public fun String.toByteArray(charset: Charset = Charsets.UTF_8): ByteArray = (this as java.lang.String).getBytes(charset)
 
 deprecated("Use toByteArray() instead to emphasize copy behaviour")
@@ -151,7 +394,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 of this sequence specified by given [range].
  */
 public fun CharSequence.slice(range: IntRange): CharSequence {
     return subSequence(range.start, range.end + 1) // inclusive

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

@@ -4,42 +4,80 @@ package kotlin
  * Defines names for Unicode symbols used in proper Typography
  */
 public object Typography {
+    /** The character " */
     public val quote: Char = '\u0022'
+    /** The character & */
     public val amp: Char = '\u0026'
+    /** The character < */
     public val less: Char = '\u003C'
+    /** The character > */
     public val greater: Char = '\u003E'
+    /** The non-breaking space character */
     public val nbsp: Char = '\u00A0'
+    /** The character × */
     public val times: Char = '\u00D7'
+    /** The character ¢ */
     public val cent: Char = '\u00A2'
+    /** The character £ */
     public val pound: Char = '\u00A3'
+    /** The character § */
     public val section: Char = '\u00A7'
+    /** The character © */
     public val copyright: Char = '\u00A9'
+    /** The character « */
     public val leftGuillemete: Char = '\u00AB'
+    /** The character » */
     public val rightGuillemete: Char = '\u00BB'
+    /** The character ® */
     public val registered: Char = '\u00AE'
+    /** The character ° */
     public val degree: Char = '\u00B0'
+    /** The character ± */
     public val plusMinus: Char = '\u00B1'
+    /** The character ¶ */
     public val paragraph: Char = '\u00B6'
+    /** The character · */
     public val middleDot: Char = '\u00B7'
+    /** The character ½ */
     public val half: Char = '\u00BD'
+    /** The character – */
     public val ndash: Char = '\u2013'
+    /** The character — */
     public val mdash: Char = '\u2014'
+    /** The character ‘ */
     public val leftSingleQuote: Char = '\u2018'
+    /** The character ’ */
     public val rightSingleQuote: Char = '\u2019'
+    /** The character ‚ */
     public val lowSingleQuote: Char = '\u201A'
+    /** The character “ */
     public val leftDoubleQuote: Char = '\u201C'
+    /** The character ” */
     public val rightDoubleQuote: Char = '\u201D'
-    public val lowDoubleQuote: Char = '\u201D'
+    /** The character „ */
+    public val lowDoubleQuote: Char = '\u201E'
+    /** The character † */
     public val dagger: Char = '\u2020'
+    /** The character ‡ */
     public val doubleDagger: Char = '\u2021'
+    /** The character • */
     public val bullet: Char = '\u2022'
+    /** The character … */
     public val ellipsis: Char = '\u2026'
+    /** The character ′ */
     public val prime: Char = '\u2032'
+    /** The character ″ */
     public val doublePrime: Char = '\u2033'
+    /** The character € */
     public val euro: Char = '\u20AC'
+    /** The character ™ */
     public val tm: Char = '\u2122'
+    /** The character ≈ */
     public val almostEqual: Char = '\u2248'
+    /** The character ≠ */
     public val notEqual: Char = '\u2260'
+    /** The character ≤ */
     public val lessOrEqual: Char = '\u2264'
+    /** The character ≥ */
     public val greaterOrEqual: Char = '\u2265'
 }

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

@@ -1,5 +1,10 @@
 package kotlin
 
+/**
+ * Converts a function that takes one argument and returns a value of the same type to a generator function.
+ * The generator function calls this function, passing to it either [initialValue] on the first iteration
+ * or the previously returned value on subsequent iterations, and returns the returned value.
+ */
 public fun <T: Any> Function1<T, T?>.toGenerator(initialValue: T): Function0<T?> {
     var nextValue: T? = initialValue
     return {

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

@@ -6,7 +6,7 @@ import kotlin.jvm.internal.unsafe.*
 import kotlin.jvm.internal.Intrinsic
 
 /**
- * This annotation indicates what exceptions should be declared by a function when compiled to a JVM method
+ * This annotation indicates what exceptions should be declared by a function when compiled to a JVM method.
  *
  * Example:
  *
@@ -20,6 +20,8 @@ import kotlin.jvm.internal.Intrinsic
  * ```
  * String readFile(String name) throws IOException {...}
  * ```
+ *
+ * @property exceptionClasses the list of checked exception classes that may be thrown by the function.
  */
 Retention(RetentionPolicy.SOURCE)
 public annotation class throws(public vararg val exceptionClasses: Class<out Throwable>)
@@ -48,5 +50,8 @@ public inline fun <R> synchronized(lock: Any, block: () -> R): R {
     }
 }
 
+/**
+ * Returns the annotation type of this annotation.
+ */
 public fun <T : Annotation> T.annotationType() : Class<out T> =
     (this as java.lang.annotation.Annotation).annotationType() as Class<out T>

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

@@ -13,8 +13,8 @@ import java.io.Serializable
  *
  * @param A type of the first value
  * @param B type of the second value
- * @param first First value
+ * @property first First value
- * @param second Second value
+ * @property second Second value
  * @constructor Creates a new instance of Pair.
  */
 public data class Pair<out A, out B>(
@@ -29,7 +29,7 @@ public data class Pair<out A, out B>(
 }
 
 /**
- * Converts a pair into a list.
+ * Converts this pair into a list.
  */
 public fun <T> Pair<T, T>.toList(): List<T> = listOf(first, second)
 
@@ -44,9 +44,9 @@ public fun <T> Pair<T, T>.toList(): List<T> = listOf(first, second)
  * @param A type of the first value
  * @param B type of the second value
  * @param C type of the third value
- * @param first First value
+ * @property first First value
- * @param second Second value
+ * @property second Second value
- * @param third Third value
+ * @property third Third value
  */
 public data class Triple<out A, out B, out C>(
         public val first: A,
@@ -61,6 +61,6 @@ public data class Triple<out A, out B, out C>(
 }
 
 /**
- * Converts triple into a list
+ * Converts this triple into a list.
  */
 public fun <T> Triple<T, T, T>.toList(): List<T> = listOf(first, second, third)

libraries/tools/kotlin-stdlib-gen/src/generators/GenerateDownTos.kt

@@ -32,6 +32,11 @@ private fun generateDownTos(outputFile: File, header: String) {
         }
 
         writer.println("""
+/**
+ * Returns a progression from this value down to the specified [to] value.
+ *
+ * The [to] value has to be less than this value.
+ */
 public fun $fromType.downTo(to: $toType): $progressionType {
     return $progressionType($fromExpr, $toExpr, $incrementExpr)
 }""")

libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt

@@ -277,7 +277,7 @@ fun elements(): List<GenericFunction> {
     templates add f("first(predicate: (T) -> Boolean)") {
         inline(true)
 
-        doc { """"Returns the first element matching the given [predicate].
+        doc { """Returns the first element matching the given [predicate].
         @throws NoSuchElementException if no such element is found.""" }
         doc(Strings) { """Returns the first character matching the given [predicate].
         @throws NoSuchElementException if no such character is found.""" }
@@ -293,8 +293,8 @@ fun elements(): List<GenericFunction> {
     templates add f("firstOrNull(predicate: (T) -> Boolean)") {
         inline(true)
 
-        doc { "Returns first element matching the given [predicate], or `null` if element was not found" }
+        doc { "Returns the first element matching the given [predicate], or `null` if element was not found" }
-        doc(Strings) { "Returns first character matching the given [predicate], or `null` if character was not found" }
+        doc(Strings) { "Returns the first character matching the given [predicate], or `null` if character was not found" }
         returns("T?")
         body {
             """