Add a note about *Raw functions behavior.

libraries/stdlib/src/generated/_Arrays.kt

@@ -437,6 +437,7 @@ public operator fun ShortArray.contains(element: Short): Boolean {
 
 /**
  * Returns `true` if [element] is found in the collection.
+ * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T> Array<out T>.containsRaw(element: Any?): Boolean {
@@ -1524,6 +1525,7 @@ public inline fun ShortArray.indexOfLast(predicate: (Short) -> Boolean): Int {
 
 /**
  * Returns first index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T> Array<out T>.indexOfRaw(element: Any?): Int {
@@ -1846,6 +1848,7 @@ public fun ShortArray.lastIndexOf(element: Short): Int {
 
 /**
  * Returns last index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T> Array<out T>.lastIndexOfRaw(element: Any?): Int {

libraries/stdlib/src/generated/_Collections.kt

@@ -63,6 +63,7 @@ public operator fun <T> Iterable<T>.contains(element: T): Boolean {
 
 /**
  * Returns `true` if [element] is found in the collection.
+ * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Iterable<*>.containsRaw(element: Any?): Boolean {
@@ -312,6 +313,7 @@ public inline fun <T> List<T>.indexOfLast(predicate: (T) -> Boolean): Int {
 
 /**
  * Returns first index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Iterable<*>.indexOfRaw(element: Any?): Int {
@@ -320,6 +322,7 @@ public inline fun Iterable<*>.indexOfRaw(element: Any?): Int {
 
 /**
  * Returns first index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T> List<T>.indexOfRaw(element: Any?): Int {
@@ -408,6 +411,7 @@ public fun <T> Iterable<T>.lastIndexOf(element: T): Int {
 
 /**
  * Returns last index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Iterable<*>.lastIndexOfRaw(element: Any?): Int {
@@ -416,6 +420,7 @@ public inline fun Iterable<*>.lastIndexOfRaw(element: Any?): Int {
 
 /**
  * Returns last index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T> List<T>.lastIndexOfRaw(element: Any?): Int {

libraries/stdlib/src/generated/_Sequences.kt

@@ -21,6 +21,7 @@ public operator fun <T> Sequence<T>.contains(element: T): Boolean {
 
 /**
  * Returns `true` if [element] is found in the collection.
+ * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Sequence<*>.containsRaw(element: Any?): Boolean {
@@ -160,6 +161,7 @@ public inline fun <T> Sequence<T>.indexOfLast(predicate: (T) -> Boolean): Int {
 
 /**
  * Returns first index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Sequence<*>.indexOfRaw(element: Any?): Int {
@@ -213,6 +215,7 @@ public fun <T> Sequence<T>.lastIndexOf(element: T): Int {
 
 /**
  * Returns last index of [element], or -1 if the collection does not contain element.
+ * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Sequence<*>.lastIndexOfRaw(element: Any?): Int {

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

@@ -105,18 +105,24 @@ public operator fun <K,V> Map<K,V>.contains(key : K) : Boolean = containsKey(key
 
 /**
  * Returns the value corresponding to the given [key], or `null` if such a key is not present in the map.
+
+ * Allows to overcome type-safety restriction of `get` that requires to pass a key of type `Key`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <K, V> Map<K, V>.getRaw(key: Any?): V? = (this as Map<Any?, V>).get(key)
 
 /**
  * Returns `true` if the map contains the specified [key].
+ *
+ * Allows to overcome type-safety restriction of `containsKey` that requires to pass a key of type `Key`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <K> Map<K, *>.containsKeyRaw(key: Any?): Boolean = (this as Map<Any?, *>).containsKey(key)
 
 /**
  * Returns `true` if the map maps one or more keys to the specified [value].
+ *
+ * Allows to overcome type-safety restriction of `containsValue` that requires to pass a value of type `V`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <K> Map<K, *>.containsValueRaw(value: Any?): Boolean = (this as Map<K, Any?>).containsValue(value)

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

@@ -5,6 +5,8 @@ package kotlin
 
 /**
  * Checks if all elements in the specified collection are contained in this collection.
+ *
+ * Allows to overcome type-safety restriction of `containsAll` that requires to pass a collection of type `Collection<E>`.
  */
 @Suppress("NOTHING_TO_INLINE")
 public inline fun Collection<*>.containsAllRaw(collection: Collection<Any?>): Boolean = (this as Collection<Any?>).containsAll(collection)
@@ -13,6 +15,8 @@ public inline fun Collection<*>.containsAllRaw(collection: Collection<Any?>): Bo
  * Removes a single instance of the specified element from this
  * collection, if it is present.
  *
+ * Allows to overcome type-safety restriction of `remove` that requires to pass an element of type `E`.
+ *
  * @return `true` if the element has been successfully removed; `false` if it was not present in the collection.
  */
 @Suppress("NOTHING_TO_INLINE")
@@ -20,6 +24,8 @@ public inline fun <E> MutableCollection<E>.removeRaw(element: Any?): Boolean = (
 
 /**
  * Removes all of this collection's elements that are also contained in the specified collection.
+
+ * Allows to overcome type-safety restriction of `removeAll` that requires to pass a collection of type `Collection<E>`.
  *
  * @return `true` if any of the specified elements was removed from the collection, `false` if the collection was not modified.
  */
@@ -29,6 +35,8 @@ public inline fun <E> MutableCollection<E>.removeAllRaw(collection: Collection<A
 /**
  * Retains only the elements in this collection that are contained in the specified collection.
  *
+ * Allows to overcome type-safety restriction of `retailAll` that requires to pass a collection of type `Collection<E>`.
+ *
  * @return `true` if any element was removed from the collection, `false` if the collection was not modified.
  */
 @Suppress("NOTHING_TO_INLINE")

libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt

@@ -27,7 +27,12 @@ fun elements(): List<GenericFunction> {
 
     templates add f("containsRaw(element: Any?)") {
         only(Iterables, Sequences, ArraysOfObjects)
-        doc { "Returns `true` if [element] is found in the collection." }
+        doc {
+            """
+            Returns `true` if [element] is found in the collection.
+            Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`.
+            """
+        }
         receiverAsterisk(Iterables, Sequences) { true }
         inline(true)
         annotations("""@Suppress("NOTHING_TO_INLINE")""")
@@ -84,7 +89,12 @@ fun elements(): List<GenericFunction> {
 
     templates add f("indexOfRaw(element: Any?)") {
         only(Iterables, Sequences, ArraysOfObjects, Lists)
-        doc { "Returns first index of [element], or -1 if the collection does not contain element." }
+        doc {
+            """
+            Returns first index of [element], or -1 if the collection does not contain element.
+            Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
+            """
+        }
         receiverAsterisk(Iterables, Sequences) { true }
         inline(true)
         annotations("""@Suppress("NOTHING_TO_INLINE")""")
@@ -143,7 +153,12 @@ fun elements(): List<GenericFunction> {
 
     templates add f("lastIndexOfRaw(element: Any?)") {
         only(Iterables, Sequences, ArraysOfObjects, Lists)
-        doc { "Returns last index of [element], or -1 if the collection does not contain element." }
+        doc {
+            """
+            Returns last index of [element], or -1 if the collection does not contain element.
+            Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
+            """
+        }
         receiverAsterisk(Iterables, Sequences) { true }
         inline(true)
         annotations("""@Suppress("NOTHING_TO_INLINE")""")