discourage usage of expect(BigDecimal).notToEqual except for null

moreover:
- improve the samples, include a `fails` case

apis/fluent/atrium-api-fluent/src/jvmMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/bigDecimalExpectations.kt

@@ -23,7 +23,7 @@ import java.math.BigDecimal
         "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
     ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
 )
-@Suppress("UNUSED_PARAMETER", "unused")
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
 fun <T : BigDecimal> Expect<T>.toEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
@@ -42,14 +42,15 @@ fun <T : BigDecimal> Expect<T>.toEqual(expected: T): Nothing =
  *
  * @since 0.17.0
  */
-@Suppress("UNUSED_PARAMETER", "unused")
+//TODO rename to toEqualNullable with 2.0.0
 @JvmName("toBeNullable")
 @Deprecated(
     "Use `toEqualNumerically` if you expect that the following assertion holds:\n" +
         "`expect(BigDecimal(\"10\")).toEqual(BigDecimal(\"10.0\"))`\n" +
         "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
     ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
 )
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
 fun <T : BigDecimal?> Expect<T>.toEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
@@ -61,10 +62,11 @@ fun <T : BigDecimal?> Expect<T>.toEqual(expected: T): Nothing =
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
- * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.toEqual
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.toEqualNull
  *
  * @since 0.17.0
  */
+//TODO rename to toEqualNul with 2.0.0
 @JvmName("toBeNull")
 fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
     _logicAppend { toBe(expected) }
@@ -79,8 +81,6 @@ fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
  * ```
  * However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use [notToEqualIncludingScale].
  *
- * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.notToEqual
- *
  * @since 0.17.0
  */
 @Deprecated(
@@ -89,13 +89,27 @@ fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
         "However, if you expect it to hold (because `BigDecimal.scale` differ), then use `notToEqualIncludingScale`.",
     ReplaceWith("notToEqualNumerically(expected) or notToEqualIncludingScale(expected)")
 )
-@Suppress("UNUSED_PARAMETER", "unused")
-fun <T : BigDecimal> Expect<T>.notToEqual(expected: T): Nothing =
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
+fun <T : BigDecimal?> Expect<T>.notToEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
             "If you know it and want that `scale` is included in the comparison, then use `notToEqualIncludingScale`."
     )
 
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is not `null`.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.notToEqualNull
+ *
+ * @since 1.1.0
+ */
+@JvmName("notToEqualNull")
+fun <T : BigDecimal> Expect<T?>.notToEqual(expected: Nothing?): Expect<T> =
+    _logicAppend { notToBe(expected) }._logic.changeSubject.unreported { it!! }
+
+
 /**
  * Expects that the subject of `this` expectation (a [BigDecimal]) is numerically equal to [expected].
  *

apis/fluent/atrium-api-fluent/src/jvmTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/BigDecimalExpectationSamples.kt

@@ -8,26 +8,27 @@ import kotlin.test.Test
 class BigDecimalExpectationSamples {
 
     @Test
-    fun toEqual() {
-        // only use toEqual to check against null, otherwise use toEqualNumerically or toEqualIncludingScale
+    fun toEqualNull() {
+        // Use toEqual only to check against null if your subject is a BigDecimal
+        // Use toEqualNumerically or toEqualIncludingScale if you want to compare it against another BigDecimal
         expect(null as BigDecimal?).toEqual(null)
-    }
 
+        fails {
+            expect(BigDecimal("-12345.6789") as BigDecimal?).toEqual(null)
+        }
+    }
 
     @Test
-    fun notToEqual() {
-        // only use notToEqual to check against null, otherwise use notToEqualNumerically or notToEqualIncludingScale
-        expect(null as BigDecimal?).notToEqual(BigDecimal("-12345.6789"))
-        expect(null as BigDecimal?).notToEqual(BigDecimal("1.0"))
-        expect(null as BigDecimal?).notToEqual(BigDecimal("25.0"))
-
-
-        expect(null as BigDecimal?).notToEqual(BigDecimal(-12345.6789))
-        expect(null as BigDecimal?).notToEqual(BigDecimal(1.0))
-        expect(null as BigDecimal?).notToEqual(BigDecimal(25.0))
+    fun notToEqualNull() {
+        // Use notToEqual only to check against null if your subject is a BigDecimal
+        // Use notToEqualNumerically or notToEqualIncludingScale if you want to compare it against another BigDecimal
+        expect(BigDecimal("-12345.6789") as BigDecimal?).notToEqual(null)
+
+        fails {
+            expect(null as BigDecimal?).notToEqual(null)
+        }
     }
 
-
     @Test
     fun toEqualNumerically() {
         expect(BigDecimal("10")).toEqualNumerically(BigDecimal("10.0"))
@@ -38,6 +39,10 @@ class BigDecimalExpectationSamples {
         expect(BigDecimal(10)).toEqualNumerically(BigDecimal(10.0))
         expect(BigDecimal(1213669989183)).toEqualNumerically(BigDecimal(1213669989183))
         expect(BigDecimal(1238126387123)).toEqualNumerically(BigDecimal(1238126387123))
+
+        fails {
+            expect(BigDecimal(10)).toEqualNumerically(BigDecimal(10.1))
+        }
     }
 
 
@@ -50,6 +55,12 @@ class BigDecimalExpectationSamples {
         expect(BigDecimal(10)).notToEqualNumerically(BigDecimal(1213669989183))
         expect(BigDecimal(1213669989183)).notToEqualNumerically(BigDecimal(10))
         expect(BigDecimal(1238126387123)).notToEqualNumerically(BigDecimal(-1.0))
+
+        fails {
+            // because is numerically the same
+            // use notToEqualIncludingScale if you want to compare the scale as well
+            expect(BigDecimal("10")).notToEqualNumerically(BigDecimal("10.0"))
+        }
     }
 
 
@@ -61,6 +72,11 @@ class BigDecimalExpectationSamples {
 
         expect(BigDecimal(10.0)).toEqualIncludingScale(BigDecimal(10.0))
         expect(BigDecimal(456.0)).toEqualIncludingScale(BigDecimal(456.0))
+
+        fails {
+            // because scale is different, use toEqualNumerically if you want to ignore the scale
+            expect(BigDecimal("10")).toEqualIncludingScale(BigDecimal("10.0"))
+        }
     }
 
 
@@ -73,7 +89,9 @@ class BigDecimalExpectationSamples {
         expect(BigDecimal(10)).notToEqualIncludingScale(BigDecimal(10.01))
         expect(BigDecimal(456.01)).notToEqualIncludingScale(BigDecimal(456))
         expect(BigDecimal(-1.456)).notToEqualIncludingScale(BigDecimal(-1.45))
-    }
-
 
+        fails {
+            expect(BigDecimal("10.0")).notToEqualIncludingScale(BigDecimal("10.0"))
+        }
+    }
 }

apis/infix/atrium-api-infix/src/jvmMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt

@@ -23,7 +23,7 @@ import java.math.BigDecimal
         "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
     ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
 )
-@Suppress("UNUSED_PARAMETER", "unused")
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
 infix fun <T : BigDecimal> Expect<T>.toEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
@@ -42,14 +42,15 @@ infix fun <T : BigDecimal> Expect<T>.toEqual(expected: T): Nothing =
  *
  * @since 0.17.0
  */
-@Suppress("UNUSED_PARAMETER", "unused")
+//TODO rename to toEqualNullable with 2.0.0
 @JvmName("toBeNullable")
 @Deprecated(
     "Use `toEqualNumerically` if you expect that the following assertion holds:\n" +
         "`expect(BigDecimal(\"10\")).toBe(BigDecimal(\"10.0\"))`\n" +
         "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
     ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
 )
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
 infix fun <T : BigDecimal?> Expect<T>.toEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
@@ -61,10 +62,11 @@ infix fun <T : BigDecimal?> Expect<T>.toEqual(expected: T): Nothing =
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
- * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.toEqual
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.toEqualNull
  *
  * @since 0.17.0
  */
+//TODO rename to toEqualNul with 2.0.0
 @JvmName("toBeNull")
 infix fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
     _logicAppend { toBe(expected) }
@@ -87,13 +89,27 @@ infix fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
         "However, if you expect it to hold (because `BigDecimal.scale` differ), then use `notToEqualIncludingScale`.",
     ReplaceWith("notToEqualNumerically(expected) or notToEqualIncludingScale(expected)")
 )
-@Suppress("UNUSED_PARAMETER", "unused")
-infix fun <T : BigDecimal> Expect<T>.notToEqual(expected: T): Nothing =
+@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter")
+infix fun <T : BigDecimal?> Expect<T>.notToEqual(expected: T): Nothing =
     throw PleaseUseReplacementException(
         "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
             "If you know it and want that `scale` is included in the comparison, then use `notToEqualIncludingScale`."
     )
 
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is not `null`.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.notToEqualNull
+ *
+ * @since 1.1.0
+ */
+@JvmName("notToEqualNull")
+infix fun <T : BigDecimal> Expect<T?>.notToEqual(expected: Nothing?): Expect<T> =
+    _logicAppend { notToBe(expected) }._logic.changeSubject.unreported { it!! }
+
+
 /**
  * Expects that the subject of `this` expectation (a [BigDecimal]) is numerically equal to [expected].
  *

apis/infix/atrium-api-infix/src/jvmTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt

@@ -8,8 +8,24 @@ import kotlin.test.Test
 class BigDecimalExpectationSamples {
 
     @Test
-    fun toEqual() {
-        // only use toEqual to check against null, otherwise use toEqualNumerically or toEqualIncludingScale
-        expect(null as BigDecimal?).toEqual(null)
+    fun toEqualNull() {
+        // Use toEqual only to check against null if your subject is a BigDecimal
+        // Use toEqualNumerically or toEqualIncludingScale if you want to compare it against another BigDecimal
+        expect(null as BigDecimal?) toEqual null
+
+        fails {
+            expect(BigDecimal("-12345.6789") as BigDecimal?) toEqual null
+        }
+    }
+
+    @Test
+    fun notToEqualNull() {
+        // Use notToEqual only to check against null if your subject is a BigDecimal
+        // Use notToEqualNumerically or notToEqualIncludingScale if you want to compare it against another BigDecimal
+        expect(BigDecimal("-12345.6789") as BigDecimal?) notToEqual null
+
+        fails {
+            expect(null as BigDecimal?) notToEqual null
+        }
     }
 }