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