diff --git a/runtime/src/main/kotlin/kotlin/collections/AbstractMutableList.kt b/runtime/src/main/kotlin/kotlin/collections/AbstractMutableList.kt index ec5dec4f493..fdcd6b71e73 100644 --- a/runtime/src/main/kotlin/kotlin/collections/AbstractMutableList.kt +++ b/runtime/src/main/kotlin/kotlin/collections/AbstractMutableList.kt @@ -24,6 +24,11 @@ public actual abstract class AbstractMutableList 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 diff --git a/runtime/src/main/kotlin/kotlin/reflect/KProperty.kt b/runtime/src/main/kotlin/kotlin/reflect/KProperty.kt index 8d013c6a0c3..a3cb7552ef3 100644 --- a/runtime/src/main/kotlin/kotlin/reflect/KProperty.kt +++ b/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. * diff --git a/runtime/src/main/kotlin/kotlin/test/Annotation.kt b/runtime/src/main/kotlin/kotlin/test/Annotation.kt index 18dafbcfcb8..5ba1c0ac107 100644 --- a/runtime/src/main/kotlin/kotlin/test/Annotation.kt +++ b/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) diff --git a/runtime/src/main/kotlin/kotlin/test/Assertions.kt b/runtime/src/main/kotlin/kotlin/test/Assertions.kt index 73068aed0f2..6eed1b4377a 100644 --- a/runtime/src/main/kotlin/kotlin/test/Assertions.kt +++ b/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 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 assertFailsWith(exceptionClass: KClass, 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 assertFailsWith(exceptionClass: KClass, message: String?, block: () -> Unit): T { try { block()