Standard library documentation updates.

core/builtins/native/kotlin/Annotation.kt

@@ -16,4 +16,9 @@
 
 package kotlin
 
+/**
+ * Base trait implicitly implemented by all annotation interfaces.
+ * See [Kotlin language documentation](http://kotlinlang.org/docs/reference/annotations.html) for more information
+ * on annotations.
+ */
 public trait Annotation

core/builtins/native/kotlin/Any.kt

@@ -16,10 +16,34 @@
 
 package kotlin
 
+/**
+ * The root of the Kotlin class hierarchy. Every Kotlin class has [Any] as a superclass.
+ */
 public open class Any {
+    /**
+     * Indicates whether some other object is "equal to" this one. Implementations must fulfil the following
+     * requirements:
+     *
+     * * Reflexive: for any non-null reference value x, x.equals(x) should return true.
+     * * Symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
+     * * Transitive:  for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true
+     * * Consistent:  for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
+     *
+     * Note that the `==` operator in Kotlin code is translated into a call to [equals] when objects on both sides of the
+     * operator are not null.
+     */
     public open fun equals(other: Any?): Boolean
 
+    /**
+     * Returns a hash code value for the object.  The general contract of hashCode is:
+     *
+     * * Whenever it is invoked on the same object more than once, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified.
+     * * If two objects are equal according to the equals() method, then calling the hashCode method on each of the two objects must produce the same integer result.
+     */
     public open fun hashCode(): Int
 
+    /**
+     * Returns a string representation of the object.
+     */
     public open fun toString(): String
 }

core/builtins/native/kotlin/Array.kt

@@ -16,13 +16,44 @@
 
 package kotlin
 
+/**
+ * Represents an array (specifically, a Java array when targeting the JVM platform).
+ * Array instances can be created using the [array] and [arrayOfNulls] standard
+ * library functions.
+ * See [Kotlin language documentation](http://kotlinlang.org/docs/reference/basic-types.html#arrays)
+ * for more information on arrays.
+ */
 public class Array<reified T> private (): Cloneable {
+    /**
+     * Returns the array element at the specified [index]. This method can be called using the
+     * index operator:
+     * ```
+     * value = arr[index]
+     * ```
+     */
     public fun get(index: Int): T
+
+    /**
+     * Sets the array element at the specified [index] to the specified [value]. This method can
+     * be called using the index operator:
+     * ```
+     * arr[index] = value
+     * ```
+     */
     public fun set(index: Int, value: T): Unit
 
+    /**
+     * Returns the number of elements in the array.
+     */
     public fun size(): Int
 
+    /**
+     * Creates an iterator for iterating over the elements of the array.
+     */
     public fun iterator(): Iterator<T>
 
+    /**
+     * Creates a shallow copy of the array.
+     */
     public override fun clone(): Array<T>
 }

core/builtins/native/kotlin/Iterator.kt

@@ -16,26 +16,67 @@
 
 package kotlin
 
+/**
+ * An iterator over a collection or another entity that can be represented as a sequence of elements.
+ * Allows to sequentially access the elements.
+ */
 public trait Iterator<out T> {
+    /**
+     * Returns the next element in the iteration.
+     */
     public fun next(): T
+
+    /**
+     * Returns `true` if the iteration has more elements.
+     */
     public fun hasNext(): Boolean
 }
 
+/**
+ * An iterator over a mutable collection. Provides the ability to remove elements while iterating.
+ * @see MutableCollection.iterator
+ */
 public trait MutableIterator<out T> : Iterator<T> {
+    /**
+     * Removes from the underlying collection the last element returned by this iterator.
+     */
     public fun remove(): Unit
 }
 
+/**
+ * An iterator over a collection that supports indexed access.
+ * @see List.listIterator
+ */
 public trait ListIterator<out T> : Iterator<T> {
     // Query Operations
     override fun next(): T
     override fun hasNext(): Boolean
 
+    /**
+     * Returns `true` if there are elements in the iteration before the current element.
+     */
     public fun hasPrevious(): Boolean
+
+    /**
+     * Returns the previous element in the iteration and moves the cursor position backwards.
+     */
     public fun previous(): T
+
+    /**
+     * Returns the index of the element that would be returned by a subsequent call to [next].
+     */
     public fun nextIndex(): Int
+
+    /**
+     * Returns the index of the element that would be returned by a subsequent call to [previous].
+     */
     public fun previousIndex(): Int
 }
 
+/**
+ * An iterator over a mutable collection that supports indexed access. Provides the ability
+ * to add, modify and remove elements while iterating.
+ */
 public trait MutableListIterator<T> : ListIterator<T>, MutableIterator<T> {
     // Query Operations
     override fun next(): T
@@ -43,6 +84,19 @@ public trait MutableListIterator<T> : ListIterator<T>, MutableIterator<T> {
 
     // Modification Operations
     override fun remove(): Unit
+
+    /**
+     * Replaces the last element returned by [next] or [previous] with the specified element [e].
+     */
     public fun set(e: T): Unit
+
+    /**
+     * Adds the specified element [e] into the underlying collection immediately before the element that would be
+     * returned by [next], if any, and after the element that would be returned by [previous], if any.
+     * (If the collection contains no elements, the new element becomes the sole element in the collection.)
+     * The new element is inserted before the implicit cursor: a subsequent call to [next] would be unaffected,
+     * and a subsequent call to [previous] would return the new element. (This call increases by one the value \
+     * that would be returned by a call to [nextIndex] or [previousIndex].)
+     */
     public fun add(e: T): Unit
 }

core/builtins/native/kotlin/Library.kt

@@ -16,13 +16,32 @@
 
 package kotlin
 
+/**
+ * Returns true if the receiver and the [other] object are the same object instance, or if they
+ * are both null.
+ */
 public fun Any?.identityEquals(other: Any?): Boolean // = this === other
 
+/**
+ * Returns true if the receiver and the [other] object are "equal" to each other, or if they are
+ * both null.
+ * @see Any.equals
+ */
 public fun Any?.equals(other: Any?): Boolean
 
-// Returns "null" for null
+/**
+ * Returns a string representation of the object. Can be called with a null receiver, in which case
+ * it returns the string "null".
+ */
 public fun Any?.toString(): String
 
+/**
+ * Concatenates this string with the string representation of the given [other] object. If either the receiver
+ * or the [other] object are null, they are represented as the string "null".
+ */
 public fun String?.plus(other: Any?): String
 
+/**
+ * Returns an array of objects of the given type with the given [size], initialized with null values.
+ */
 public fun arrayOfNulls<reified T>(size: Int): Array<T?>

core/builtins/native/kotlin/Nothing.kt

@@ -17,6 +17,7 @@
 package kotlin
 
 /**
- * Nothing has no instances
+ * Nothing has no instances. You can use Nothing to represent "a value that never exists": for example,
+ * if a function has the return type of Nothing, it means that it never returns (always throws an exception).
  */
 public class Nothing private () {}