KT-20357 Add samples for Map.containsValue

Co-authored-by: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>

libraries/stdlib/samples/test/samples/collections/maps.kt

@@ -142,6 +142,22 @@ class Maps {
             val sameMap = nonEmptyMap.ifEmpty { null }
             assertTrue(nonEmptyMap === sameMap)
         }
+
+        @Sample
+        fun containsValue() {
+            val map: Map<String, Int> = mapOf("x" to 1, "y" to 2)
+
+            // member containsValue is used
+            assertTrue(map.containsValue(1))
+
+            // extension containsValue is used when the argument type is a supertype of the map value type
+            assertTrue(map.containsValue(1 as Number))
+            assertTrue(map.containsValue(2 as Any))
+
+            assertFalse(map.containsValue("string" as Any))
+
+            // map.containsValue("string") // cannot call extension when the argument type and the map value type are unrelated at all
+        }
     }
 
     class Filtering {

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

@@ -211,6 +211,8 @@ public inline fun <@kotlin.internal.OnlyInputTypes K> Map<out K, *>.containsKey(
  * 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`.
+ *
+ * @sample samples.collections.Maps.Usage.containsValue
  */
 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") // false warning, extension takes precedence in some cases
 @kotlin.internal.InlineOnly