Unify stdlib docs with common stdlib, part 2 (#2260)

* Unify kotlin.test docs

* Duplicate MutableList.add docs in AbstractMutableList.add

Because the documentation inheritance doesn't work as desired here.

* Minor: delimit summary in KProperty docs

runtime/src/main/kotlin/kotlin/collections/AbstractMutableList.kt

@@ -24,6 +24,11 @@ public actual abstract class AbstractMutableList<E> protected actual constructor
     abstract override fun removeAt(index: Int): E
     abstract override fun set(index: Int, element: E): E
 
+    /**
+     * Adds the specified element to the end of this list.
+     *
+     * @return `true` because the list is always modified as the result of this operation.
+     */
     override actual fun add(element: E): Boolean {
         add(size, element)
         return true

runtime/src/main/kotlin/kotlin/reflect/KProperty.kt

@@ -10,6 +10,7 @@ import kotlin.native.internal.FixmeReflection
 /**
  * Represents a property, such as a named `val` or `var` declaration.
  * Instances of this class are obtainable by the `::` operator.
+ *
  * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/reflection.html)
  * for more information.
  *

runtime/src/main/kotlin/kotlin/test/Annotation.kt

@@ -42,7 +42,7 @@ public annotation class BeforeEach
 public annotation class AfterEach
 
 /**
- * Marks a test or a suite as ignored/pending.
+ * Marks a test or a suite as ignored.
  */
 @Retention(AnnotationRetention.SOURCE)
 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)

runtime/src/main/kotlin/kotlin/test/Assertions.kt

@@ -90,10 +90,22 @@ public fun <@OnlyInputTypes T> expect(expected: T, message: String?, block: () -
     assertEquals(expected, block(), message)
 }
 
-/** Asserts that given function [block] fails by throwing an exception. */
+/**
+ * Asserts that given function [block] fails by throwing an exception.
+ *
+ * @return An exception that was expected to be thrown and was successfully caught.
+ * The returned exception can be inspected further, for example by asserting its property values.
+ */
 public 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.
+ *
+ * @return An exception that was expected to be thrown and was successfully caught.
+ * The returned exception can be inspected further, for example by asserting its property values.
+ */
 @SinceKotlin("1.1")
 public fun assertFails(message: String?, block: () -> Unit): Throwable {
     try {
@@ -106,28 +118,46 @@ public 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.
+ *
+ * @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.
  */
+
 @InlineOnly
 public inline fun <reified T : Throwable> assertFailsWith(message: String? = null, noinline block: () -> Unit) : T =
         assertFailsWith(T::class, message, block)
 
-/** 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.
+ *
+ * @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.
+ */
 public fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, block: () -> Unit): T =
         assertFailsWith(exceptionClass, null, block)
 
 
 // From AssertionsH.kt
 /**
- * Comments out a block of test code until it is implemented while keeping a link to the code
- * to implement in your unit test output
+ * Takes the given [block] of test code and _doesn't_ execute it.
+ *
+ * This keeps the code under test referenced, but doesn't actually test it until it is implemented.
  */
 @Suppress("UNUSED_PARAMETER")
 public inline fun todo(block: () -> Unit) {
     println("TODO")
 }
 
-/** 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.
+ *
+ * @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.
+ */
 public fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Unit): T {
     try {
         block()