Add samples for fun0 assertions (#991)

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/fun0Assertions.kt

@@ -16,6 +16,8 @@ import kotlin.reflect.KClass
  * the element type is actually `String`.
  *
  * @return An [Expect] with the new type [TExpected].
+ *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.Fun0ExpectationSamples.toThrowFeature
  */
 inline fun <reified TExpected : Throwable> Expect<out () -> Any?>.toThrow(): Expect<TExpected> =
     toThrow(TExpected::class).transform()
@@ -56,6 +58,8 @@ internal fun <TExpected : Throwable> Expect<out () -> Any?>.toThrow(
  * the element type is actually `String`.
  *
  * @return An [Expect] with the new type [TExpected].
+ *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.Fun0ExpectationSamples.toThrow
  */
 inline fun <reified TExpected : Throwable> Expect<out () -> Any?>.toThrow(
     noinline assertionCreator: Expect<TExpected>.() -> Unit
@@ -67,6 +71,8 @@ inline fun <reified TExpected : Throwable> Expect<out () -> Any?>.toThrow(
  * and changes the subject of `this` expectation to the return value of type [R].
  *
  * @return An [Expect] with the new type [R].
+ *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.Fun0ExpectationSamples.notToThrowFeature
  */
 fun <R, T : () -> R> Expect<T>.notToThrow(): Expect<R> =
     _logic.notToThrow().transform()
@@ -76,6 +82,8 @@ fun <R, T : () -> R> Expect<T>.notToThrow(): Expect<R> =
  * and that the corresponding return value holds all assertions the given [assertionCreator] creates.
  *
  * @return An [Expect] with the new type [R].
+ *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.Fun0ExpectationSamples.notToThrow
  */
 fun <R, T : () -> R> Expect<T>.notToThrow(
     assertionCreator: Expect<R>.() -> Unit

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/Fun0ExpectationSamples.kt

@@ -0,0 +1,61 @@
+package ch.tutteli.atrium.api.fluent.en_GB.samples
+
+import ch.tutteli.atrium.api.fluent.en_GB.*
+import ch.tutteli.atrium.api.verbs.internal.expect
+import kotlin.test.Test
+
+class Fun0ExpectationSamples {
+
+    @Test
+    fun toThrowFeature() {
+        expect { throw IllegalStateException("abc") }
+            .toThrow<IllegalStateException>() // subject is now of type IllegalStateException
+            .messageToContain("abc")
+
+        fails {
+            expect { throw IllegalStateException("abc") }
+                .toThrow<IndexOutOfBoundsException>()
+                .messageToContain("abc") // not shown in reporting as `toThrow<IndexOutOfBoundsException>()` already fails
+        }
+    }
+
+    @Test
+    fun toThrow() {
+        expect { throw IllegalStateException("abc") }
+            .toThrow<IllegalStateException> { // subject inside this block is of type IllegalStateException
+                messageToContain("abc")
+            }
+
+        fails { // because wrong type expected (IndexOutOfBoundsException instead of IllegalStateException), but since we use a block...
+            expect { throw IllegalStateException("abc") }
+                .toThrow<IndexOutOfBoundsException> {
+                    messageToContain("abc") // ... reporting mentions that subject's message was expected `to contain: "abc"`
+                }
+        }
+    }
+
+    @Test
+    fun notToThrowFeature() {
+        expect { "abc" }
+            .notToThrow() // subject is now of type String
+            .toContain("abc")
+
+        fails {
+            expect { throw IllegalStateException("abc") }
+                .notToThrow()
+        }
+    }
+
+    @Test
+    fun notToThrow() {
+        expect { "abc" }
+            .notToThrow { // subject is now of type String
+                toEqual("abc")
+            }
+
+        fails {
+            expect { throw IllegalStateException("abc") }
+                .notToThrow {}
+        }
+    }
+}