Clarify the purpose of the message parameter of assertFailsWith

#KT-22869 Fixed

libraries/kotlin.test/common/src/main/kotlin/kotlin/test/Assertions.kt

@@ -102,7 +102,11 @@ fun <@OnlyInputTypes T> expect(expected: T, message: String?, block: () -> T) {
 /** Asserts that given function [block] fails by throwing an exception. */
 fun assertFails(block: () -> Unit): Throwable = assertFails(null, block)
 
-/** Asserts that given function [block] fails by throwing an exception. */
+/**
+ * Asserts that given function [block] fails by throwing an exception.
+ *
+ * If the assertion fails, the specified [message] is used unless it is null as a prefix for the failure message.
+ */
 @SinceKotlin("1.1")
 fun assertFails(message: String?, block: () -> Unit): Throwable {
     try {
@@ -115,7 +119,8 @@ fun assertFails(message: String?, block: () -> Unit): Throwable {
 }
 
 /** Asserts that a [block] fails with a specific exception of type [T] being thrown.
- *  Since inline method doesn't allow to trace where it was invoked, it is required to pass a [message] to distinguish this method call from others.
+ *
+ * If the assertion fails, the specified [message] is used unless it is null as a prefix for the failure message.
  */
 @InlineOnly
 inline fun <reified T : Throwable> assertFailsWith(message: String? = null, noinline block: () -> Unit): T =

libraries/kotlin.test/common/src/main/kotlin/kotlin/test/AssertionsH.kt

@@ -13,5 +13,9 @@ import kotlin.reflect.KClass
  */
 expect fun todo(block: () -> Unit)
 
-/** Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown. */
+/**
+ * Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown.
+ *
+ * If the assertion fails, the specified [message] is used unless it is null as a prefix for the failure message.
+ */
 expect fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Unit): T

libraries/kotlin.test/js/src/main/kotlin/kotlin/test/JsImpl.kt

@@ -17,7 +17,11 @@ actual fun todo(block: () -> Unit) {
 }
 
 
-/** Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown. */
+/**
+ * Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown.
+ *
+ * If the assertion fails, the specified [message] is used unless it is null as a prefix for the failure message.
+ */
 actual fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Unit): T {
     val exception = assertFails(message, block)
     @Suppress("INVISIBLE_MEMBER")

libraries/kotlin.test/jvm/src/main/kotlin/AssertionsImpl.kt

@@ -32,7 +32,11 @@ private fun <T : Throwable> assertFailsWithImpl(exceptionClass: Class<T>, messag
 }
 
 
-/** Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown. */
+/**
+ * Asserts that a [block] fails with a specific exception of type [exceptionClass] being thrown.
+ *
+ * If the assertion fails, the specified [message] is used unless it is null as a prefix for the failure message.
+ */
 actual fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Unit): T =
     assertFailsWithImpl(exceptionClass.java, message, block)