provide documentation for generated built-in classes

core/builtins/native/kotlin/Arrays.kt

@@ -18,89 +18,153 @@
 
 package kotlin
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Byte
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Byte): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): ByteIterator
 
     public override fun clone(): ByteArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Char
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Char): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): CharIterator
 
     public override fun clone(): CharArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Short
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Short): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): ShortIterator
 
     public override fun clone(): ShortArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Int
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Int): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): IntIterator
 
     public override fun clone(): IntArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Long
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Long): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): LongIterator
 
     public override fun clone(): LongArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Float
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Float): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): FloatIterator
 
     public override fun clone(): FloatArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Double
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Double): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): DoubleIterator
 
     public override fun clone(): DoubleArray
 }
 
+/**
+ * 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 {
+    /** Returns the array element at the given [index]. This method can be called using the index operator. */
     public fun get(index: Int): Boolean
+    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */
     public fun set(index: Int, value: Boolean): Unit
 
+    /** Returns the number of elements in the array. */
     public fun size(): Int
 
+    /** Creates an iterator over the elements of the array. */
     public fun iterator(): BooleanIterator
 
     public override fun clone(): BooleanArray

core/builtins/src/kotlin/Iterators.kt

@@ -18,51 +18,67 @@
 
 package kotlin
 
+/** An iterator over a sequence of values of type Byte. */
 public abstract class ByteIterator : Iterator<Byte> {
     override final fun next() = nextByte()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextByte(): Byte
 }
 
+/** An iterator over a sequence of values of type Char. */
 public abstract class CharIterator : Iterator<Char> {
     override final fun next() = nextChar()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextChar(): Char
 }
 
+/** An iterator over a sequence of values of type Short. */
 public abstract class ShortIterator : Iterator<Short> {
     override final fun next() = nextShort()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextShort(): Short
 }
 
+/** An iterator over a sequence of values of type Int. */
 public abstract class IntIterator : Iterator<Int> {
     override final fun next() = nextInt()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextInt(): Int
 }
 
+/** An iterator over a sequence of values of type Long. */
 public abstract class LongIterator : Iterator<Long> {
     override final fun next() = nextLong()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextLong(): Long
 }
 
+/** An iterator over a sequence of values of type Float. */
 public abstract class FloatIterator : Iterator<Float> {
     override final fun next() = nextFloat()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextFloat(): Float
 }
 
+/** An iterator over a sequence of values of type Double. */
 public abstract class DoubleIterator : Iterator<Double> {
     override final fun next() = nextDouble()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextDouble(): Double
 }
 
+/** An iterator over a sequence of values of type Boolean. */
 public abstract class BooleanIterator : Iterator<Boolean> {
     override final fun next() = nextBoolean()
 
+    /** Returns the next value in the sequence without boxing. */
     public abstract fun nextBoolean(): Boolean
 }
 

core/builtins/src/kotlin/ProgressionIterators.kt

@@ -20,6 +20,7 @@ package kotlin
 
 import kotlin.internal.getProgressionFinalElement
 
+/** An iterator over a progression of values of type Byte. */
 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()
@@ -39,6 +40,7 @@ class ByteProgressionIterator(start: Byte, end: Byte, val increment: Int) : Byte
     }
 }
 
+/** An iterator over a progression of values of type Char. */
 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()
@@ -58,6 +60,7 @@ class CharProgressionIterator(start: Char, end: Char, val increment: Int) : Char
     }
 }
 
+/** An iterator over a progression of values of type Short. */
 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()
@@ -77,6 +80,7 @@ class ShortProgressionIterator(start: Short, end: Short, val increment: Int) : S
     }
 }
 
+/** An iterator over a progression of values of type Int. */
 class IntProgressionIterator(start: Int, end: Int, val increment: Int) : IntIterator() {
     private var next = start
     private val finalElement: Int = getProgressionFinalElement(start, end, increment)
@@ -96,6 +100,7 @@ class IntProgressionIterator(start: Int, end: Int, val increment: Int) : IntIter
     }
 }
 
+/** An iterator over a progression of values of type Long. */
 class LongProgressionIterator(start: Long, end: Long, val increment: Long) : LongIterator() {
     private var next = start
     private val finalElement: Long = getProgressionFinalElement(start, end, increment)
@@ -115,6 +120,7 @@ class LongProgressionIterator(start: Long, end: Long, val increment: Long) : Lon
     }
 }
 
+/** An iterator over a progression of values of type Float. */
 class FloatProgressionIterator(start: Float, val end: Float, val increment: Float) : FloatIterator() {
     private var next = start
 
@@ -127,6 +133,7 @@ class FloatProgressionIterator(start: Float, val end: Float, val increment: Floa
     }
 }
 
+/** An iterator over a progression of values of type Double. */
 class DoubleProgressionIterator(start: Double, val end: Double, val increment: Double) : DoubleIterator() {
     private var next = start
 

core/builtins/src/kotlin/Progressions.kt

@@ -18,6 +18,9 @@
 
 package kotlin
 
+/**
+ * A progression of values of type Byte.
+ */
 public class ByteProgression(
         override val start: Byte,
         override val end: Byte,
@@ -29,6 +32,7 @@ public class ByteProgression(
 
     override fun iterator(): ByteIterator = ByteProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -41,6 +45,9 @@ public class ByteProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Char.
+ */
 public class CharProgression(
         override val start: Char,
         override val end: Char,
@@ -52,6 +59,7 @@ public class CharProgression(
 
     override fun iterator(): CharIterator = CharProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -64,6 +72,9 @@ public class CharProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Short.
+ */
 public class ShortProgression(
         override val start: Short,
         override val end: Short,
@@ -75,6 +86,7 @@ public class ShortProgression(
 
     override fun iterator(): ShortIterator = ShortProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -87,6 +99,9 @@ public class ShortProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Int.
+ */
 public class IntProgression(
         override val start: Int,
         override val end: Int,
@@ -98,6 +113,7 @@ public class IntProgression(
 
     override fun iterator(): IntIterator = IntProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -110,6 +126,9 @@ public class IntProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Long.
+ */
 public class LongProgression(
         override val start: Long,
         override val end: Long,
@@ -121,6 +140,7 @@ public class LongProgression(
 
     override fun iterator(): LongIterator = LongProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -133,6 +153,9 @@ public class LongProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Float.
+ */
 public class FloatProgression(
         override val start: Float,
         override val end: Float,
@@ -145,6 +168,7 @@ public class FloatProgression(
 
     override fun iterator(): FloatIterator = FloatProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =
@@ -157,6 +181,9 @@ public class FloatProgression(
     override fun toString(): String = if (increment > 0) "$start..$end step $increment" else "$start downTo $end step ${-increment}"
 }
 
+/**
+ * A progression of values of type Double.
+ */
 public class DoubleProgression(
         override val start: Double,
         override val end: Double,
@@ -169,6 +196,7 @@ public class DoubleProgression(
 
     override fun iterator(): DoubleIterator = DoubleProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =

core/builtins/src/kotlin/Ranges.kt

@@ -18,6 +18,9 @@
 
 package kotlin
 
+/**
+ * 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
         get() = 1
@@ -36,10 +39,14 @@ public class ByteRange(override val start: Byte, override val end: Byte) : Range
         if (isEmpty()) -1 else (31 * start.toInt() + end)
 
     class object {
+        /** An empty range of values of type Byte. */
         public val EMPTY: ByteRange = ByteRange(1, 0)
     }
 }
 
+/**
+ * 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
         get() = 1
@@ -58,10 +65,14 @@ public class CharRange(override val start: Char, override val end: Char) : Range
         if (isEmpty()) -1 else (31 * start.toInt() + end)
 
     class object {
+        /** An empty range of values of type Char. */
         public val EMPTY: CharRange = CharRange(1.toChar(), 0.toChar())
     }
 }
 
+/**
+ * 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
         get() = 1
@@ -80,10 +91,14 @@ public class ShortRange(override val start: Short, override val end: Short) : Ra
         if (isEmpty()) -1 else (31 * start.toInt() + end)
 
     class object {
+        /** An empty range of values of type Short. */
         public val EMPTY: ShortRange = ShortRange(1, 0)
     }
 }
 
+/**
+ * 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
         get() = 1
@@ -102,10 +117,14 @@ public class IntRange(override val start: Int, override val end: Int) : Range<In
         if (isEmpty()) -1 else (31 * start + end)
 
     class object {
+        /** An empty range of values of type Int. */
         public val EMPTY: IntRange = IntRange(1, 0)
     }
 }
 
+/**
+ * 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
         get() = 1
@@ -124,10 +143,14 @@ public class LongRange(override val start: Long, override val end: Long) : Range
         if (isEmpty()) -1 else (31 * (start xor (start ushr 32)) + (end xor (end ushr 32))).toInt()
 
     class object {
+        /** An empty range of values of type Long. */
         public val EMPTY: LongRange = LongRange(1, 0)
     }
 }
 
+/**
+ * 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
         get() = 1.0f
@@ -146,10 +169,14 @@ public class FloatRange(override val start: Float, override val end: Float) : Ra
         if (isEmpty()) -1 else (31 * java.lang.Float.floatToIntBits(start) + java.lang.Float.floatToIntBits(end))
 
     class object {
+        /** An empty range of values of type Float. */
         public val EMPTY: FloatRange = FloatRange(1.0f, 0.0f)
     }
 }
 
+/**
+ * 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
         get() = 1.0
@@ -173,6 +200,7 @@ public class DoubleRange(override val start: Double, override val end: Double) :
     }
 
     class object {
+        /** An empty range of values of type Double. */
         public val EMPTY: DoubleRange = DoubleRange(1.0, 0.0)
     }
 }

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

@@ -25,13 +25,23 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
     override fun generateBody() {
         for (kind in PrimitiveType.values()) {
+            val typeLower = kind.name().toLowerCase()
             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(" * @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 {")
+            out.println("    /** Returns the array element at the given [index]. This method can be called using the index operator. */")
             out.println("    public fun get(index: Int): $s")
+            out.println("    /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */")
             out.println("    public fun set(index: Int, value: $s): Unit")
             out.println()
+            out.println("    /** Returns the number of elements in the array. */")
             out.println("    public fun size(): Int")
             out.println()
+            out.println("    /** Creates an iterator over the elements of the array. */")
             out.println("    public fun iterator(): ${s}Iterator")
             out.println()
             out.println("    public override fun clone(): ${s}Array")

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

@@ -24,9 +24,11 @@ class GenerateIterators(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     override fun generateBody() {
         for (kind in PrimitiveType.values()) {
             val s = kind.capitalized
-            out.println("public abstract class ${s}Iterator : Iterator<$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()
+            out.println("    /** Returns the next value in the sequence without boxing. */")
             out.println("    public abstract fun next$s(): $s")
             out.println("}")
             out.println()

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

@@ -31,7 +31,8 @@ fun integerProgressionIterator(kind: ProgressionKind): String {
         else -> "" to ""
     }
 
-    return """class ${t}ProgressionIterator(start: $t, end: $t, val increment: $incrementType) : ${t}Iterator() {
+    return """/** An iterator over a progression of values of type $t. */
+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
     private var hasNext: Boolean = if (increment > 0) start <= end else start >= end
@@ -54,7 +55,8 @@ fun integerProgressionIterator(kind: ProgressionKind): String {
 fun floatingPointProgressionIterator(kind: ProgressionKind): String {
     val t = kind.capitalized
 
-    return """class ${t}ProgressionIterator(start: $t, val end: $t, val increment: $t) : ${t}Iterator() {
+    return """/** An iterator over a progression of values of type $t. */
+class ${t}ProgressionIterator(start: $t, val end: $t, val increment: $t) : ${t}Iterator() {
     private var next = start
 
     override fun hasNext(): Boolean = if (increment > 0) next <= end else next >= end

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

@@ -65,7 +65,10 @@ class GenerateProgressions(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             }
 
             out.println(
-"""public class $progression(
+"""/**
+ * A progression of values of type $t.
+ */
+public class $progression(
         override val start: $t,
         override val end: $t,
         override val increment: $incrementType
@@ -76,6 +79,7 @@ class GenerateProgressions(out: PrintWriter) : BuiltInsSourceGenerator(out) {
 
     override fun iterator(): ${t}Iterator = ${t}ProgressionIterator(start, end, increment)
 
+    /** Checks if the progression is empty. */
     public fun isEmpty(): Boolean = if (increment > 0) start > end else start < end
 
     override fun equals(other: Any?): Boolean =

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

@@ -63,7 +63,10 @@ class GenerateRanges(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             }
 
             out.println(
-"""public class $range(override val start: $t, override val end: $t) : Range<$t>, Progression<$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
         get() = $increment
 
@@ -80,6 +83,7 @@ class GenerateRanges(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     override fun hashCode(): Int $hashCode
 
     class object {
+        /** An empty range of values of type $t. */
         public val EMPTY: $range = $range($emptyBounds)
     }
 }""")