Provide KDoc for js collection implementations.

js/js.libraries/src/core/collections/ArrayList.kt

@@ -16,9 +16,23 @@
 
 package kotlin.collections
 
+/**
+ * Provides a [MutableList] implementation, which uses a resizable array as its backing storage.
+ *
+ * This implementation doesn't provide a way to manage capacity, as backing JS array is resizeable itself.
+ * There is no speed advantage to pre-allocating array sizes in JavaScript, so this implementation does not include any of the
+ * capacity and "growth increment" concepts.
+ */
 public open class ArrayList<E> internal constructor(private var array: Array<Any?>) : AbstractMutableList<E>(), RandomAccess {
 
+    /**
+     * Creates an empty [ArrayList].
+     * @param capacity initial capacity (ignored)
+     */
     public constructor(capacity: Int = 0) : this(emptyArray()) {}
+    /**
+     * Creates an [ArrayList] filled from the [elements] collection.
+     */
     public constructor(elements: Collection<E>) : this(elements.toTypedArray<Any?>()) {}
 
     /** Does nothing in this ArrayList implementation. */

js/js.libraries/src/core/collections/EqualityComparator.kt

@@ -18,14 +18,13 @@ package kotlin.collections
 
 internal interface EqualityComparator {
     /**
-     * Subclasses must override to return a whether or not two keys or values are
-     * equal.
+     * Subclasses must override to return a value indicating
+     * whether or not two keys or values are equal.
      */
     abstract fun equals(value1: Any?, value2: Any?): Boolean
 
     /**
-     * Subclasses must override to return a hash code for a given key. The key is
-     * guaranteed to be non-null and not a String.
+     * Subclasses must override to return the hash code of a given key.
      */
     abstract fun getHashCode(value: Any?): Int
 

js/js.libraries/src/core/collections/HashMap.kt

@@ -23,6 +23,11 @@ package kotlin.collections
 import kotlin.collections.Map.Entry
 import kotlin.collections.MutableMap.MutableEntry
 
+/**
+ * Hash table based implementation of the [MutableMap] interface.
+ *
+ * This implementation makes no guarantees regarding the order of enumeration of [keys], [elements] and [entries] collections.
+ */
 public open class HashMap<K, V> : AbstractMutableMap<K, V> {
 
     private inner class EntrySet : AbstractMutableSet<MutableEntry<K, V>>() {
@@ -60,14 +65,28 @@ public open class HashMap<K, V> : AbstractMutableMap<K, V> {
         this.equality = internalMap.equality
     }
 
+    /**
+     * Constructs an empty [HashMap] instance.
+     */
     constructor() : this(InternalHashCodeMap(EqualityComparator.HashCode))
 
+    /**
+     * Constructs an empty [HashMap] instance.
+     *
+     * @param  initialCapacity the initial capacity (ignored)
+     * @param  loadFactor      the load factor (ignored)
+     *
+     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     */
     constructor(initialCapacity: Int, loadFactor: Float = 0f) : this() {
         // This implementation of HashMap has no need of load factors or capacities.
         require(initialCapacity >= 0) { "Negative initial capacity" }
         require(loadFactor >= 0) { "Non-positive load factor" }
     }
 
+    /**
+     * Constructs an instance of [HashMap] filled with the contents of the specified [original] map.
+     */
     constructor(original: Map<out K, V>) : this() {
         this.putAll(original)
     }
@@ -101,7 +120,10 @@ public open class HashMap<K, V> : AbstractMutableMap<K, V> {
 
 }
 
-
+/**
+ * Constructs the specialized implementation of [HashMap] with [String] keys, which stores the keys as properties of
+ * JS object without hashing them.
+ */
 public fun <V> stringMapOf(vararg pairs: Pair<String, V>): HashMap<String, V> {
     return HashMap<String, V>(InternalStringMap(EqualityComparator.HashCode)).apply { putAll(pairs) }
 }

js/js.libraries/src/core/collections/HashSet.kt

@@ -20,20 +20,36 @@
 
 package kotlin.collections
 
-
+/**
+ * The implementation of the [MutableSet] interface, backed by a [HashMap] instance.
+ */
 public open class HashSet<E> : AbstractMutableSet<E> {
 
     private val map: HashMap<E, Any>
 
+    /**
+     * Constructs a new empty [HashSet].
+     */
     constructor() {
         map = HashMap<E, Any>()
     }
 
-    constructor(c: Collection<E>) {
-        map = HashMap<E, Any>(c.size)
-        addAll(c)
+    /**
+     * Constructs a new [HashSet] filled with the elements of the specified collection.
+     */
+    constructor(elements: Collection<E>) {
+        map = HashMap<E, Any>(elements.size)
+        addAll(elements)
     }
 
+    /**
+     * Constructs a new empty [HashSet].
+     *
+     * @param  initialCapacity the initial capacity (ignored)
+     * @param  loadFactor      the load factor (ignored)
+     *
+     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     */
     constructor(initialCapacity: Int, loadFactor: Float = 0.0f) {
         map = HashMap<E, Any>(initialCapacity, loadFactor)
     }
@@ -73,6 +89,10 @@ public open class HashSet<E> : AbstractMutableSet<E> {
 
 }
 
+/**
+ * Creates a new instance of the specialized implementation of [HashSet] with the specified [String] elements,
+ * which elements the keys as properties of JS object without hashing them.
+ */
 public fun stringSetOf(vararg elements: String): HashSet<String> {
     return HashSet(stringMapOf<Any>()).apply { addAll(elements) }
 }

js/js.libraries/src/core/collections/LinkedHashMap.kt

@@ -21,6 +21,12 @@ package kotlin.collections
 
 import kotlin.collections.MutableMap.MutableEntry
 
+/**
+ * Hash table based implementation of the [MutableMap] interface, which additionally preserves the insertion order
+ * of entries during the iteration.
+ *
+ * The insertion order is preserved by maintaining a doubly-linked list of all of its entries.
+ */
 public open class LinkedHashMap<K, V> : HashMap<K, V>, Map<K, V> {
 
     /**
@@ -160,6 +166,9 @@ public open class LinkedHashMap<K, V> : HashMap<K, V>, Map<K, V> {
    */
     private val map: HashMap<K, ChainEntry<K, V>>
 
+    /**
+     * Constructs an empty [LinkedHashMap] instance.
+     */
     constructor() : super()  {
         map = HashMap<K, ChainEntry<K, V>>()
     }
@@ -168,10 +177,21 @@ public open class LinkedHashMap<K, V> : HashMap<K, V>, Map<K, V> {
         map = backingMap as HashMap<K, ChainEntry<K, V>>
     }
 
+    /**
+     * Constructs an empty [LinkedHashMap] instance.
+     *
+     * @param  initialCapacity the initial capacity (ignored)
+     * @param  loadFactor      the load factor (ignored)
+     *
+     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     */
     constructor(initialCapacity: Int, loadFactor: Float = 0f) : super(initialCapacity, loadFactor) {
         map = HashMap<K, ChainEntry<K, V>>()
     }
 
+    /**
+     * Constructs an instance of [LinkedHashMap] filled with the contents of the specified [original] map.
+     */
     constructor(original: Map<out K, V>) {
         map = HashMap<K, ChainEntry<K, V>>()
         this.putAll(original)
@@ -231,7 +251,10 @@ public open class LinkedHashMap<K, V> : HashMap<K, V>, Map<K, V> {
 
 }
 
-
+/**
+ * Constructs the specialized implementation of [LinkedHashMap] with [String] keys, which stores the keys as properties of
+ * JS object without hashing them.
+ */
 public fun <V> linkedStringMapOf(vararg pairs: Pair<String, V>): LinkedHashMap<String, V> {
     return LinkedHashMap<String, V>(stringMapOf<Any>()).apply { putAll(pairs) }
 }

js/js.libraries/src/core/collections/LinkedHashSet.kt

@@ -20,16 +20,34 @@
 
 package kotlin.collections
 
+/**
+ * The implementation of the [MutableSet] interface, backed by a [LinkedHashMap] instance.
+ *
+ * This implementation preserves the insertion order of elements during the iteration.
+ */
 public open class LinkedHashSet<E> : HashSet<E> {
 
     internal constructor(map: LinkedHashMap<E, Any>) : super(map)
 
+    /**
+     * Constructs a new empty [LinkedHashSet].
+     */
     constructor() : super(LinkedHashMap<E, Any>())
 
-    constructor(c: Collection<E>) : super(LinkedHashMap<E, Any>()) {
-        addAll(c)
+    /**
+     * Constructs a new [LinkedHashSet] filled with the elements of the specified collection.
+     */
+    constructor(elements: Collection<E>) : super(LinkedHashMap<E, Any>()) {
+        addAll(elements)
     }
-
+    /**
+     * Constructs a new empty [LinkedHashSet].
+     *
+     * @param  initialCapacity the initial capacity (ignored)
+     * @param  loadFactor      the load factor (ignored)
+     *
+     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     */
     constructor(initialCapacity: Int, loadFactor: Float = 0.0f) : super(LinkedHashMap<E, Any>(initialCapacity, loadFactor))
 
 //    public override fun clone(): Any {
@@ -38,6 +56,10 @@ public open class LinkedHashSet<E> : HashSet<E> {
 
 }
 
+/**
+ * Creates a new instance of the specialized implementation of [LinkedHashSet] with the specified [String] elements,
+ * which elements the keys as properties of JS object without hashing them.
+ */
 public fun linkedStringSetOf(vararg elements: String): LinkedHashSet<String> {
     return LinkedHashSet(linkedStringMapOf<Any>()).apply { addAll(elements) }
 }

js/js.libraries/src/core/collections/RandomAccess.kt

@@ -16,4 +16,7 @@
 
 package kotlin.collections
 
+/**
+ * Marker interface indicating that the [List] implementation supports fast indexed access.
+ */
 public interface RandomAccess