[JS IR] Add comments

^KT-59001

libraries/stdlib/js/src/kotlin/collections/HashMap.kt

@@ -96,8 +96,8 @@ public actual open class HashMap<K, V> : AbstractMutableMap<K, V>, MutableMap<K,
 }
 
 /**
- * Constructs the specialized implementation of [HashMap] with [String] keys, which stores the keys as properties of
+ * Constructs the specialized implementation of [HashMap] with [String] keys,
- * JS object without hashing them.
+ * 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()).apply { putAll(pairs) }

libraries/stdlib/js/src/kotlin/collections/HashMapEntry.kt

@@ -5,6 +5,11 @@
 
 package kotlin.collections
 
+/**
+ * This is the most performant implementations of [HashMap.keys] container.
+ * It is implemented over [InternalMap] interface and can not be used without it.
+ * [HashMapKeys] is more efficient than the implementation [HashMapKeysDefault] from HashMapEntryDefault.kt.
+ */
 internal class HashMapKeys<E> internal constructor(
     private val backing: InternalMap<E, *>,
 ) : MutableSet<E>, AbstractMutableSet<E>() {
@@ -21,6 +26,11 @@ internal class HashMapKeys<E> internal constructor(
     override fun checkIsMutable() = backing.checkIsMutable()
 }
 
+/**
+ * This is the most performant implementations of [HashMap.values] container.
+ * It is implemented over [InternalMap] interface and can not be used without it.
+ * [HashMapValues] is more efficient than the implementation [HashMapValuesDefault] from HashMapEntryDefault.kt.
+ */
 internal class HashMapValues<V> internal constructor(
     private val backing: InternalMap<*, V>,
 ) : MutableCollection<V>, AbstractMutableCollection<V>() {
@@ -68,6 +78,10 @@ internal abstract class HashMapEntrySetBase<K, V, E : Map.Entry<K, V>> internal
     override fun checkIsMutable() = backing.checkIsMutable()
 }
 
+/**
+ * This is the implementations of [HashMap.entries] container.
+ * It is implemented over [InternalMap] interface and can not be used without it.
+ */
 internal class HashMapEntrySet<K, V> internal constructor(
     backing: InternalMap<K, V>,
 ) : HashMapEntrySetBase<K, V, MutableMap.MutableEntry<K, V>>(backing) {

libraries/stdlib/js/src/kotlin/collections/HashMapEntryDefault.kt

@@ -5,6 +5,11 @@
 
 package kotlin.collections
 
+/**
+ * This is a default implementations of [AbstractMutableMap.keys] container.
+ * It is implemented over [AbstractMutableMap] and can be used directly from [AbstractMutableMap].
+ * [HashMapKeysDefault] is less efficient than the implementation [HashMapKeys] from HashMapEntry.kt.
+ */
 internal class HashMapKeysDefault<K, V>(private val backingMap: AbstractMutableMap<K, V>) : AbstractMutableSet<K>() {
     override fun add(element: K): Boolean = throw UnsupportedOperationException("Add is not supported on keys")
     override fun clear() = backingMap.clear()
@@ -33,6 +38,11 @@ internal class HashMapKeysDefault<K, V>(private val backingMap: AbstractMutableM
     override fun checkIsMutable(): Unit = backingMap.checkIsMutable()
 }
 
+/**
+ * This is a default implementations of [AbstractMutableMap.values] container.
+ * They are implemented over [AbstractMutableMap] and can be used directly from [AbstractMutableMap].
+ * [HashMapValuesDefault] is efficient than the implementations [HashMapValues] from HashMapEntry.kt.
+ */
 internal class HashMapValuesDefault<K, V>(private val backingMap: AbstractMutableMap<K, V>) : AbstractMutableCollection<V>() {
     override fun add(element: V): Boolean = throw UnsupportedOperationException("Add is not supported on values")
     override fun clear() = backingMap.clear()

libraries/stdlib/js/src/kotlin/collections/HashSet.kt

@@ -10,7 +10,7 @@
 package kotlin.collections
 
 /**
- * The implementation of the [MutableSet] interface, backed by a [HashMap] instance.
+ * The implementation of the [MutableSet] interface, backed by a [InternalMap] implementation.
  */
 // Classes that extend HashSet and implement `build()` (freezing) operation
 // have to make sure mutating methods check `checkIsMutable`.

libraries/stdlib/js/src/kotlin/collections/InternalHashMap.kt

@@ -5,6 +5,11 @@
 
 package kotlin.collections
 
+/**
+ * This is an open addressing hash map implementation.
+ *
+ * Copied from libraries/stdlib/native-wasm/src/kotlin/collections/HashMap.kt
+ */
 internal class InternalHashMap<K, V> private constructor(
     // keys in insert order
     private var keysArray: Array<K>,

libraries/stdlib/js/src/kotlin/collections/InternalStringLinkedMap.kt

@@ -5,6 +5,19 @@
 
 package kotlin.collections
 
+/**
+ * Extends [InternalStringMap] by preserving the insertion order.
+ *
+ * Two [IntArray]s are used to implement a linked list:
+ *  the [nextIndexes] Array keeps the next indexes of the corresponding node,
+ *  the [prevIndexes] Array keeps the previous indexes of the corresponding node.
+ *
+ * When adding a new key, we append its previous index (which points to the tail) to the end of the [prevIndexes] Array
+ * and update the next index of the tail. The last element of the [nextIndexes] array for the new key is set to [EMPTY_INDEX].
+ *
+ * When removing a key, we update the next and previous indexes of adjacent nodes
+ * and move the last next-prev pair to the position of the removing key.
+ */
 internal class InternalStringLinkedMap<K, V> : InternalStringMap<K, V>() {
     companion object {
         private const val EMPTY_INDEX = -1

libraries/stdlib/js/src/kotlin/collections/InternalStringMap.kt

@@ -31,11 +31,34 @@ private inline fun <E> JsRawArray<E>.replaceElementAtWithLast(index: Int) {
 }
 
 /**
- * A simple wrapper around JavaScript Map for key type is string.
+ * A simple wrapper around JavaScript Object for key type is string.
  *
  * Though this map is instantiated only with K=String, the K type is not fixed to String statically,
  * because we want to have it erased to Any? in order not to generate type-safe override bridges for
  * [get], [contains], [remove] etc, if they ever are generated.
+ *
+ * The string map has the following structure:
+ * A JavaScript Object keeps a mapping from a string key to an integer index:
+ *      { <key 0>: 0, <key 1>: 1, ..., <key n>: n }
+ *
+ * Two separate JavaScript Arrays store key-value pairs corresponding to their indexes:
+ *      [<key 0>, <key 1>, ..., <key n>]
+ *      [<val 0>, <val 1>, ..., <val n>]
+ *
+ * When adding a new key-value pair, we append them to the end of the Arrays:
+ *      [<key 0>, <key 1>, ..., <key n>, <key n+1>]
+ *      [<val 0>, <val 1>, ..., <val n>, <val n+1>]
+ * and then set the new key with the last index in the Object:
+ *      { <key 0>: 0, <key 1>: 1, ..., <key n>: n, <key n+1>: n + 1 }
+ *
+ * When removing a pair, we retrieve the index from the Object:
+ *      { <key 0>: 0, [[[<key 1>: 1]]], ..., <key n>: n, <key n+1>: n + 1 }
+ *                    ^remove <key 1>^
+ * and replace the removing pair with the last pair:
+ *      [<key 0>, <key n+1>, ..., <key n>]
+ *      [<val 0>, <val n+1>, ..., <val n>]
+ * After that, we update the moved key's index in the Object:
+ *      { <key 0>: 0, <key n+1>: 1, ..., <key n>: n }
  */
 internal open class InternalStringMap<K, V> : InternalMap<K, V> {
     private fun createJsMap(): dynamic {

libraries/stdlib/js/src/kotlin/collections/LinkedHashMap.kt

@@ -10,10 +10,10 @@
 package kotlin.collections
 
 /**
- * Hash table based implementation of the [MutableMap] interface, which additionally preserves the insertion order
+ * Hash table based implementation of the [MutableMap] interface,
- * of entries during the iteration.
+ * which additionally preserves the insertion order of entries during the iteration.
  *
- * The insertion order is preserved natively by the HashMap implementation.
+ * The insertion order is preserved by the corresponding [InternalMap] implementation.
  */
 public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
     /**
@@ -74,8 +74,8 @@ public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
 }
 
 /**
- * Constructs the specialized implementation of [LinkedHashMap] with [String] keys, which stores the keys as properties of
+ * Constructs the specialized implementation of [LinkedHashMap] with [String] keys,
- * JS object without hashing them.
+ * 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>(InternalStringLinkedMap()).apply { putAll(pairs) }

libraries/stdlib/js/src/kotlin/collections/LinkedHashSet.kt

@@ -10,9 +10,9 @@
 package kotlin.collections
 
 /**
- * The implementation of the [MutableSet] interface, backed by a [LinkedHashMap] instance.
+ * The implementation of the [MutableSet] interface, backed by a [InternalMap] implementation.
  *
- * The insertion order is preserved natively by the HashSet implementation.
+ * The insertion order is preserved by the corresponding [InternalMap] implementation.
  */
 public actual open class LinkedHashSet<E> : HashSet<E>, MutableSet<E> {
     /**