KT-15363 Rename expectedSize to capacity and edit docs

libraries/stdlib/src/kotlin/collections/Collections.kt

@@ -155,7 +155,11 @@ public inline fun <T> MutableList(size: Int, init: (index: Int) -> T): MutableLi
 }
 
 /**
- * Build a new read-only [List] with the [elements][E] from the [builderAction].
+ * Builds a new read-only [List] by populating a [MutableList] using the given [builderAction]
+ * and returning a read-only list with the same elements.
+ *
+ * The list passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
  *
  * @sample samples.collections.Builders.Lists.buildListSample
  */
@@ -168,18 +172,25 @@ public inline fun <E> buildList(@BuilderInference builderAction: MutableList<E>.
 }
 
 /**
- * Build a new read-only [List] with the given [expectedSize] and [elements][E] from the [builderAction].
+ * Builds a new read-only [List] by populating a [MutableList] using the given [builderAction]
+ * and returning a read-only list with the same elements.
+ *
+ * The list passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
+ *
+ * [capacity] is used to hint the expected number of elements added in the [builderAction].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Lists.buildListSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <E> buildList(expectedSize: Int, @BuilderInference builderAction: MutableList<E>.() -> Unit): List<E> {
+public inline fun <E> buildList(capacity: Int, @BuilderInference builderAction: MutableList<E>.() -> Unit): List<E> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return ArrayList<E>(expectedSize).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return ArrayList<E>(capacity).apply(builderAction)
 }
 
 

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -124,7 +124,13 @@ public inline fun <K, V> linkedMapOf(): LinkedHashMap<K, V> = LinkedHashMap<K, V
 public fun <K, V> linkedMapOf(vararg pairs: Pair<K, V>): LinkedHashMap<K, V> = pairs.toMap(LinkedHashMap(mapCapacity(pairs.size)))
 
 /**
- * Build a new read-only [Map] with the [key][K]-[value][V] pairs from the [builderAction] while preserving the insertion order.
+ * Builds a new read-only [Map] by populating a [MutableMap] using the given [builderAction]
+ * and returning a read-only map with the same key-value pairs.
+ *
+ * The map passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
+ *
+ * Entries of the map are iterated in the order they were added by the [builderAction].
  *
  * @sample samples.collections.Builders.Maps.buildMapSample
  */
@@ -137,19 +143,27 @@ public inline fun <K, V> buildMap(@BuilderInference builderAction: MutableMap<K,
 }
 
 /**
- * Build a new read-only [Map] with the given [expectedSize] and [key][K]-[value][V] pairs from the [builderAction] while preserving
- * the insertion order.
+ * Builds a new read-only [Map] by populating a [MutableMap] using the given [builderAction]
+ * and returning a read-only map with the same key-value pairs.
+ *
+ * The map passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
+ *
+ * [capacity] is used to hint the expected number of pairs added in the [builderAction].
+ *
+ * Entries of the map are iterated in the order they were added by the [builderAction].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Maps.buildMapSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <K, V> buildMap(expectedSize: Int, @BuilderInference builderAction: MutableMap<K, V>.() -> Unit): Map<K, V> {
+public inline fun <K, V> buildMap(capacity: Int, @BuilderInference builderAction: MutableMap<K, V>.() -> Unit): Map<K, V> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return LinkedHashMap<K, V>(mapCapacity(expectedSize)).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return LinkedHashMap<K, V>(mapCapacity(capacity)).apply(builderAction)
 }
 
 /**

libraries/stdlib/src/kotlin/collections/Sets.kt

@@ -91,7 +91,13 @@ public inline fun <T> linkedSetOf(): LinkedHashSet<T> = LinkedHashSet()
 public fun <T> linkedSetOf(vararg elements: T): LinkedHashSet<T> = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
 
 /**
- * Build a new read-only [Set] with the [elements][E] from the [builderAction] while preserving the insertion order.
+ * Builds a new read-only [Set] by populating a [MutableSet] using the given [builderAction]
+ * and returning a read-only set with the same elements.
+ *
+ * The set passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
+ *
+ * Elements of the set are iterated in the order they were added by the [builderAction].
  *
  * @sample samples.collections.Builders.Sets.buildSetSample
  */
@@ -104,19 +110,27 @@ public inline fun <E> buildSet(@BuilderInference builderAction: MutableSet<E>.()
 }
 
 /**
- * Build a new read-only [Set] with the given [expectedSize] and [elements][E] from the [builderAction] while preserving the insertion
- * order.
+ * Builds a new read-only [Set] by populating a [MutableSet] using the given [builderAction]
+ * and returning a read-only set with the same elements.
+ *
+ * The set passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
+ *
+ * [capacity] is used to hint the expected number of elements added in the [builderAction].
+ *
+ * Elements of the set are iterated in the order they were added by the [builderAction].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Sets.buildSetSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <E> buildSet(expectedSize: Int, @BuilderInference builderAction: MutableSet<E>.() -> Unit): Set<E> {
+public inline fun <E> buildSet(capacity: Int, @BuilderInference builderAction: MutableSet<E>.() -> Unit): Set<E> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return LinkedHashSet<E>(mapCapacity(expectedSize)).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return LinkedHashSet<E>(mapCapacity(capacity)).apply(builderAction)
 }