kotlin-test: Add documentation for value returned by assertFailsWith

A follow-up after https://youtrack.jetbrains.com/issue/KT-27418

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

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

@@ -36,6 +36,9 @@ private fun <T : Throwable> assertFailsWithImpl(exceptionClass: Class<T>, messag
  * 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.
+ *
+ * @return An exception of the expected exception type [T] that successfully caught.
+ * The returned exception can be inspected further, for example by asserting its property values.
  */
 actual fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Unit): T =
     assertFailsWithImpl(exceptionClass.java, message, block)