Improve documentation of collection constructors #KT-59192

libraries/stdlib/native-wasm/src/kotlin/collections/ArrayList.kt

@@ -17,11 +17,31 @@ actual class ArrayList<E> private constructor(
         private val Empty = ArrayList<Nothing>(0).also { it.isReadOnly = true }
     }
 
+    /**
+     * Creates a new empty [ArrayList].
+     */
     actual constructor() : this(10)
 
+    /**
+     * Creates a new empty [ArrayList] with the specified initial capacity.
+     *
+     * Capacity is the maximum number of elements the list is able to store in current backing storage.
+     * When the list gets full and a new element can't be added, its capacity is expanded,
+     * which usually leads to creation of a bigger backing storage.
+     *
+     * @param initialCapacity the initial capacity of the created list.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     *
+     * @throws IllegalArgumentException if [initialCapacity] is negative.
+     */
     actual constructor(initialCapacity: Int) : this(
             arrayOfUninitializedElements(initialCapacity), 0, 0, false, null, null)
 
+    /**
+     * Creates a new [ArrayList] filled with the elements of the specified collection.
+     *
+     * The iteration order of elements in the created list is the same as in the specified collection.
+     */
     actual constructor(elements: Collection<E>) : this(elements.size) {
         addAll(elements)
     }

libraries/stdlib/native-wasm/src/kotlin/collections/HashMap.kt

@@ -31,8 +31,23 @@ actual class HashMap<K, V> private constructor(
 
     // ---------------------------- functions ----------------------------
 
+    /**
+     * Creates a new empty [HashMap].
+     */
     actual constructor() : this(INITIAL_CAPACITY)
 
+    /**
+     * Creates a new empty [HashMap] with the specified initial capacity.
+     *
+     * Capacity is the maximum number of entries the map is able to store in current internal data structure.
+     * When the map gets full by a certain default load factor, its capacity is expanded,
+     * which usually leads to rebuild of the internal data structure.
+     *
+     * @param initialCapacity the initial capacity of the created map.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     *
+     * @throws IllegalArgumentException if [initialCapacity] is negative.
+     */
     actual constructor(initialCapacity: Int) : this(
             arrayOfUninitializedElements(initialCapacity),
             null,
@@ -41,11 +56,27 @@ actual class HashMap<K, V> private constructor(
             INITIAL_MAX_PROBE_DISTANCE,
             0)
 
+    /**
+     * Creates a new [HashMap] filled with the contents of the specified [original] map.
+     */
     actual constructor(original: Map<out K, V>) : this(original.size) {
         putAll(original)
     }
 
-    // This implementation doesn't use a loadFactor, this constructor is used for compatibility with common stdlib
+    /**
+     * Creates a new empty [HashMap] with the specified initial capacity and load factor.
+     *
+     * Capacity is the maximum number of entries the map is able to store in current internal data structure.
+     * Load factor is the measure of how full the map is allowed to get in relation to
+     * its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
+     *
+     * @param initialCapacity the initial capacity of the created map.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     * @param loadFactor the load factor of the created map.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     *
+     * @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
+     */
     actual constructor(initialCapacity: Int, loadFactor: Float) : this(initialCapacity)
 
     @PublishedApi

libraries/stdlib/native-wasm/src/kotlin/collections/HashSet.kt

@@ -12,15 +12,46 @@ actual class HashSet<E> internal constructor(
         private val Empty = HashSet(HashMap.EmptyHolder.value<Nothing, Nothing>())
     }
 
+    /**
+     * Creates a new empty [HashSet].
+     */
     actual constructor() : this(HashMap<E, Nothing>())
 
+    /**
+     * Creates a new empty [HashSet] with the specified initial capacity.
+     *
+     * Capacity is the maximum number of elements the set is able to store in current internal data structure.
+     * When the set gets full by a certain default load factor, its capacity is expanded,
+     * which usually leads to rebuild of the internal data structure.
+     *
+     * @param initialCapacity the initial capacity of the created set.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     *
+     * @throws IllegalArgumentException if [initialCapacity] is negative.
+     */
     actual constructor(initialCapacity: Int) : this(HashMap<E, Nothing>(initialCapacity))
 
+    /**
+     * Creates a new [HashSet] filled with the elements of the specified collection.
+     */
     actual constructor(elements: Collection<E>) : this(elements.size) {
         addAll(elements)
     }
 
-    // This implementation doesn't use a loadFactor
+    /**
+     * Creates a new empty [HashSet] with the specified initial capacity and load factor.
+     *
+     * Capacity is the maximum number of elements the set is able to store in current internal data structure.
+     * Load factor is the measure of how full the set is allowed to get in relation to
+     * its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
+     *
+     * @param initialCapacity the initial capacity of the created set.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     * @param loadFactor the load factor of the created set.
+     *   Note that the argument is just a hint for the implementation and can be ignored.
+     *
+     * @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
+     */
     actual constructor(initialCapacity: Int, loadFactor: Float) : this(initialCapacity)
 
     @PublishedApi