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

core/builtins/src/kotlin/Annotations.kt

@@ -16,10 +16,30 @@
 
 package kotlin
 
+/**
+ * Marks the annotated class as a data class. The compiler automatically generates
+ * equals()/hashCode(), toString(), componentN() and copy() functions for data classes.
+ * See [the Kotlin language documentation](http://kotlinlang.org/docs/reference/data-classes.html)
+ * for more information.
+ */
 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.
+ */
 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.
+ */
 public annotation class suppress(vararg val names: String)
 
+/**
+ * Enables the tail call optimization for the annotated function. If the annotated function
+ * calls itself recursively as the last operation it performs, it will be executed without
+ * growing the stack depth. Tail call optimization is currently only supported by the JVM
+ * backend.
+ */
 public annotation class tailRecursive

core/builtins/src/kotlin/Inline.kt

@@ -16,8 +16,20 @@
 
 package kotlin
 
+/**
+ * Annotates the parameter of a function annotated as [inline] and forbids inlining of
+ * function literals passed as arguments for this parameter.
+ */
 public annotation class noinline
 
+/**
+ * Enables inlining of the annotated function and the function literals that it takes as parameters into the
+ * 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.
+ * @see noinline
+ * @see inlineOptions
+ */
 public annotation class inline(public val strategy: InlineStrategy = InlineStrategy.AS_FUNCTION)
 
 public enum class InlineStrategy {

core/builtins/src/kotlin/Progression.kt

@@ -16,10 +16,25 @@
 
 package kotlin
 
+/**
+ * Represents a sequence of numbers or characters with a given start value, end value and step.
+ * This class is intended to be used in 'for' loops, and the JVM backend suggests efficient
+ * bytecode generation for it. Progressions with a step of -1 can be created through the
+ * `downTo` method on classes representing primitive types.
+ */
 public trait Progression<out N : Any> : Iterable<N> {
+    /**
+     * The start value of the progression.
+     */
     public val start: N
 
+    /**
+     * The end value of the progression (inclusive).
+     */
     public val end: N
 
+    /**
+     * The step of the progression.
+     */
     public val increment: Number
 }

core/builtins/src/kotlin/PropertyMetadata.kt

@@ -16,7 +16,13 @@
 
 package kotlin
 
+/**
+ * Represents a property in a Kotlin class.
+ */
 public trait PropertyMetadata {
+    /**
+     * The name of the property.
+     */
     public val name: String
 }
 

core/builtins/src/kotlin/Range.kt

@@ -16,13 +16,29 @@
 
 package kotlin
 
+/**
+ * Represents a range of values (for example, numbers or characters).
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/ranges.html) for more information.
+ */
 public trait Range<T : Comparable<T>> {
+    /**
+     * The minimum value in the range.
+     */
     public val start: T
 
+    /**
+     * The maximum value in the range (inclusive).
+     */
     public val end: T
 
+    /**
+     * Checks if the specified value belongs to the range.
+     */
     public fun contains(item: T): Boolean
 
+    /**
+     * Checks if the range is empty.
+     */
     public fun isEmpty(): Boolean = start > end
 
     override fun toString(): String = "$start..$end"

core/builtins/src/kotlin/internal/progressionUtil.kt

@@ -39,11 +39,11 @@ private fun differenceModulo(a: Long, b: Long, c: Long): Long {
 
 /**
  * Calculates the final element of a bounded arithmetic progression, i.e. the last element of the progression which is in the range
- * from {@code start} to {@code end} in case of a positive {@code increment}, or from {@code end} to {@code start} in case of a negative
+ * from [start] to [end] in case of a positive [increment], or from [end] to [start] in case of a negative
  * increment.
  *
- * <p>No validation on passed parameters is performed. The given parameters should satisfy the condition: either
- * {@code increment&nbsp;&gt; 0} and {@code start&nbsp;&lt;= end}, or {@code increment&nbsp;&lt; 0} and {@code start&nbsp;&gt;= end}.
+ * No validation on passed parameters is performed. The given parameters should satisfy the condition: either
+ * `increment > 0` and `start >= end`, or `increment < 0` and`start >= end`.
  * @param start first element of the progression
  * @param end ending bound for the progression
  * @param increment increment, or difference of successive elements in the progression
@@ -60,11 +60,11 @@ public fun getProgressionFinalElement(start: Int, end: Int, increment: Int): Int
 
 /**
  * Calculates the final element of a bounded arithmetic progression, i.e. the last element of the progression which is in the range
- * from {@code start} to {@code end} in case of a positive {@code increment}, or from {@code end} to {@code start} in case of a negative
+ * from [start] to [end] in case of a positive [increment], or from [end] to [start] in case of a negative
  * increment.
  *
- * <p>No validation on passed parameters is performed. The given parameters should satisfy the condition: either
- * {@code increment&nbsp;&gt; 0} and {@code start&nbsp;&lt;= end}, or {@code increment&nbsp;&lt; 0} and {@code start&nbsp;&gt;= end}.
+ * No validation on passed parameters is performed. The given parameters should satisfy the condition: either
+ * `increment > 0` and `start >= end`, or `increment < 0` and`start >= end`.
  * @param start first element of the progression
  * @param end ending bound for the progression
  * @param increment increment, or difference of successive elements in the progression