From 945e058586b99ab08810d3911f4967094b6dbb61 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Fri, 12 Jul 2019 18:29:30 +0300
Subject: [PATCH] Document return value of removeAll and retainAll with
 predicate

#KT-32532 Fixed
---
 .../stdlib/src/kotlin/collections/MutableCollections.kt   | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt
index 5187a9acd48..3523cf5beaa 100644
--- a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt
+++ b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt
@@ -151,11 +151,15 @@ public fun <T> MutableCollection<in T>.addAll(elements: Array<out T>): Boolean {
 
 /**
  * Removes all elements from this [MutableIterable] that match the given [predicate].
+ *
+ * @return `true` if any element was removed from this collection, or `false` when no elements were removed and collection was not modified.
  */
 public fun <T> MutableIterable<T>.removeAll(predicate: (T) -> Boolean): Boolean = filterInPlace(predicate, true)
 
 /**
  * Retains only elements of this [MutableIterable] that match the given [predicate].
+ *
+ * @return `true` if any element was removed from this collection, or `false` when all elements were retained and collection was not modified.
  */
 public fun <T> MutableIterable<T>.retainAll(predicate: (T) -> Boolean): Boolean = filterInPlace(predicate, false)
 
@@ -173,11 +177,15 @@ private fun <T> MutableIterable<T>.filterInPlace(predicate: (T) -> Boolean, pred
 
 /**
  * Removes all elements from this [MutableList] that match the given [predicate].
+ *
+ * @return `true` if any element was removed from this collection, or `false` when no elements were removed and collection was not modified.
  */
 public fun <T> MutableList<T>.removeAll(predicate: (T) -> Boolean): Boolean = filterInPlace(predicate, true)
 
 /**
  * Retains only elements of this [MutableList] that match the given [predicate].
+ *
+ * @return `true` if any element was removed from this collection, or `false` when all elements were retained and collection was not modified.
  */
 public fun <T> MutableList<T>.retainAll(predicate: (T) -> Boolean): Boolean = filterInPlace(predicate, false)