Improve documentation of collection constructors #KT-59192

libraries/stdlib/common/src/kotlin/collections/ArrayList.kt

@@ -6,8 +6,31 @@
 package kotlin.collections
 
 expect class ArrayList<E> : MutableList<E>, RandomAccess {
+
+    /**
+     * Creates a new empty [ArrayList].
+     */
     constructor()
+
+    /**
+     * 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.
+     */
     constructor(initialCapacity: Int)
+
+    /**
+     * 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.
+     */
     constructor(elements: Collection<E>)
 
     fun trimToSize()

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

@@ -6,9 +6,44 @@
 package kotlin.collections
 
 expect class HashMap<K, V> : MutableMap<K, V> {
+    /**
+     * Creates a new empty [HashMap].
+     */
     constructor()
+
+    /**
+     * 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.
+     */
     constructor(initialCapacity: Int)
+
+    /**
+     * 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.
+     */
     constructor(initialCapacity: Int, loadFactor: Float)
+
+    /**
+     * Creates a new [HashMap] filled with the contents of the specified [original] map.
+     */
     constructor(original: Map<out K, V>)
 
     // From Map

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

@@ -6,9 +6,44 @@
 package kotlin.collections
 
 expect class HashSet<E> : MutableSet<E> {
+    /**
+     * Creates a new empty [HashSet].
+     */
     constructor()
+
+    /**
+     * 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.
+     */
     constructor(initialCapacity: Int)
+
+    /**
+     * 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.
+     */
     constructor(initialCapacity: Int, loadFactor: Float)
+
+    /**
+     * Creates a new [HashSet] filled with the elements of the specified collection.
+     */
     constructor(elements: Collection<E>)
 
     // From Set

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

@@ -6,9 +6,46 @@
 package kotlin.collections
 
 expect class LinkedHashMap<K, V> : MutableMap<K, V> {
+    /**
+     * Creates a new empty [LinkedHashMap].
+     */
     constructor()
+
+    /**
+     * Creates a new empty [LinkedHashMap] 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.
+     */
     constructor(initialCapacity: Int)
+
+    /**
+     * Creates a new empty [LinkedHashMap] 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.
+     */
     constructor(initialCapacity: Int, loadFactor: Float)
+
+    /**
+     * Creates a new [LinkedHashMap] filled with the contents of the specified [original] map.
+     *
+     * The iteration order of entries in the created map is the same as in the [original] map.
+     */
     constructor(original: Map<out K, V>)
 
     // From Map

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

@@ -6,9 +6,46 @@
 package kotlin.collections
 
 expect class LinkedHashSet<E> : MutableSet<E> {
+    /**
+     * Creates a new empty [LinkedHashSet].
+     */
     constructor()
+
+    /**
+     * Creates a new empty [LinkedHashSet] 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.
+     */
     constructor(initialCapacity: Int)
+
+    /**
+     * Creates a new empty [LinkedHashSet] 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.
+     */
     constructor(initialCapacity: Int, loadFactor: Float)
+
+    /**
+     * Creates a new [LinkedHashSet] filled with the elements of the specified collection.
+     *
+     * The iteration order of elements in the created set is the same as in the specified collection.
+     */
     constructor(elements: Collection<E>)
 
     // From Set

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

@@ -20,18 +20,28 @@ public actual open class ArrayList<E> internal constructor(private var array: Ar
     private var isReadOnly: Boolean = false
 
     /**
-     * Creates an empty [ArrayList].
+     * Creates a new empty [ArrayList].
      */
     public actual constructor() : this(emptyArray()) {}
 
     /**
-     * Creates an empty [ArrayList].
+     * Creates a new empty [ArrayList] with the specified initial capacity.
-     * @param initialCapacity initial capacity (ignored)
+     *
+     * 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.
      */
     public actual constructor(initialCapacity: Int) : this(emptyArray()) {}
 
     /**
-     * Creates an [ArrayList] filled from the [elements] collection.
+     * 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.
      */
     public actual constructor(elements: Collection<E>) : this(elements.toTypedArray<Any?>()) {}
 

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

@@ -57,29 +57,47 @@ public actual open class HashMap<K, V> : AbstractMutableMap<K, V>, MutableMap<K,
     }
 
     /**
-     * Constructs an empty [HashMap] instance.
+     * Creates a new empty [HashMap].
      */
     actual constructor() : this(InternalHashCodeMap(EqualityComparator.HashCode))
 
     /**
-     * Constructs an empty [HashMap] instance.
+     * Creates a new empty [HashMap] with the specified initial capacity and load factor.
      *
-     * @param  initialCapacity the initial capacity (ignored)
+     * Capacity is the maximum number of entries the map is able to store in current internal data structure.
-     * @param  loadFactor      the load factor (ignored)
+     * 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.
      *
-     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     * @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() {
         // This implementation of HashMap has no need of load factors or capacities.
         require(initialCapacity >= 0) { "Negative initial capacity: $initialCapacity" }
-        require(loadFactor >= 0) { "Non-positive load factor: $loadFactor" }
+        require(loadFactor > 0) { "Non-positive load factor: $loadFactor" }
     }
 
+    /**
+     * 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(initialCapacity, 0.0f)
 
 
     /**
-     * Constructs an instance of [HashMap] filled with the contents of the specified [original] map.
+     * Creates a new [HashMap] filled with the contents of the specified [original] map.
      */
     actual constructor(original: Map<out K, V>) : this() {
         this.putAll(original)

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

@@ -19,14 +19,14 @@ public actual open class HashSet<E> : AbstractMutableSet<E>, MutableSet<E> {
     internal val map: HashMap<E, Any>
 
     /**
-     * Constructs a new empty [HashSet].
+     * Creates a new empty [HashSet].
      */
     actual constructor() {
         map = HashMap<E, Any>()
     }
 
     /**
-     * Constructs a new [HashSet] filled with the elements of the specified collection.
+     * Creates a new [HashSet] filled with the elements of the specified collection.
      */
     actual constructor(elements: Collection<E>) {
         map = HashMap<E, Any>(elements.size)
@@ -34,17 +34,35 @@ public actual open class HashSet<E> : AbstractMutableSet<E>, MutableSet<E> {
     }
 
     /**
-     * Constructs a new empty [HashSet].
+     * Creates a new empty [HashSet] with the specified initial capacity and load factor.
      *
-     * @param  initialCapacity the initial capacity (ignored)
+     * Capacity is the maximum number of elements the set is able to store in current internal data structure.
-     * @param  loadFactor      the load factor (ignored)
+     * 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.
      *
-     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     * @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) {
         map = HashMap<E, Any>(initialCapacity, loadFactor)
     }
 
+    /**
+     * 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(initialCapacity, 0.0f)
 
     /**

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

@@ -170,7 +170,7 @@ public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
     private var isReadOnly: Boolean = false
 
     /**
-     * Constructs an empty [LinkedHashMap] instance.
+     * Creates a new empty [LinkedHashMap].
      */
     actual constructor() : super() {
         map = HashMap<K, ChainEntry<K, V>>()
@@ -182,21 +182,41 @@ public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
     }
 
     /**
-     * Constructs an empty [LinkedHashMap] instance.
+     * Creates a new empty [LinkedHashMap] with the specified initial capacity and load factor.
      *
-     * @param  initialCapacity the initial capacity (ignored)
+     * Capacity is the maximum number of entries the map is able to store in current internal data structure.
-     * @param  loadFactor      the load factor (ignored)
+     * 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.
      *
-     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     * @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) : super(initialCapacity, loadFactor) {
         map = HashMap<K, ChainEntry<K, V>>()
     }
 
+    /**
+     * Creates a new empty [LinkedHashMap] 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(initialCapacity, 0.0f)
 
     /**
-     * Constructs an instance of [LinkedHashMap] filled with the contents of the specified [original] map.
+     * Creates a new [LinkedHashMap] filled with the contents of the specified [original] map.
+     *
+     * The iteration order of entries in the created map is the same as in the [original] map.
      */
     actual constructor(original: Map<out K, V>) {
         map = HashMap<K, ChainEntry<K, V>>()

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

@@ -24,27 +24,47 @@ public actual open class LinkedHashSet<E> : HashSet<E>, MutableSet<E> {
     internal constructor(map: LinkedHashMap<E, Any>) : super(map)
 
     /**
-     * Constructs a new empty [LinkedHashSet].
+     * Creates a new empty [LinkedHashSet].
      */
     actual constructor() : super(LinkedHashMap<E, Any>())
 
     /**
-     * Constructs a new [LinkedHashSet] filled with the elements of the specified collection.
+     * Creates a new [LinkedHashSet] filled with the elements of the specified collection.
+     *
+     * The iteration order of elements in the created set is the same as in the specified collection.
      */
     actual constructor(elements: Collection<E>) : super(LinkedHashMap<E, Any>()) {
         addAll(elements)
     }
 
     /**
-     * Constructs a new empty [LinkedHashSet].
+     * Creates a new empty [LinkedHashSet] with the specified initial capacity and load factor.
      *
-     * @param  initialCapacity the initial capacity (ignored)
+     * Capacity is the maximum number of elements the set is able to store in current internal data structure.
-     * @param  loadFactor      the load factor (ignored)
+     * 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.
      *
-     * @throws IllegalArgumentException if the initial capacity or load factor are negative
+     * @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) : super(LinkedHashMap<E, Any>(initialCapacity, loadFactor))
 
+    /**
+     * Creates a new empty [LinkedHashSet] 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(initialCapacity, 0.0f)
 
     @PublishedApi

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