provide documentation for generated built-in classes

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