[Next release] Updated docs for new json matchers

documentation/docs/assertions/android_matchers.md

@@ -2,6 +2,7 @@
 id: android_matchers
 title: Android Matchers
 slug: android-matchers.html
+sidebar_label: Android
 ---
 
 

documentation/docs/assertions/arrow.md

@@ -1,6 +1,7 @@
 ---
 title: Arrow
 slug: arrow.html
+sidebar_label: Arrow
 ---
 
 

documentation/docs/assertions/compiler.md

@@ -1,6 +1,8 @@
 ---
+id: compiler
 title: Compiler Matchers
 slug: compiler-matchers.html
+sidebar_label: Compiler
 ---
 
 

documentation/docs/assertions/core.md

@@ -2,6 +2,7 @@
 id: core
 title: Core Matchers
 slug: core-matchers.html
+sidebar_label: Core
 ---
 
 

documentation/docs/assertions/json.md

@@ -1,22 +1,122 @@
 ---
 title: Json Matchers
 slug: json-matchers.html
+sidebar_label: Json
 ---
 
+Kotest provides powerful JSON assertions in the `kotest-assertions-json` module.
+These allow flexible testing of json strings without the need to worry about formatting or ordering.
+They provide precise error messages when comparing json so that the error can be easily found in a large json structure.
 
+This module is available for JVM and JS targets.
 
+## shouldEqualJson
 
-Matchers for JSON are provided by the `kotest-assertions-json` module.
+`json.shouldEqualJson(other)` asserts that the left-hand side represents the same
+JSON structure as the right-hand side.
 
+The matcher allows for different formatting, and for different order of keys.
 
-| JSON | For convenience, JSONs are simply strings |
-| -------- | ---- |
-| `str?.shouldMatchJson(json?)` | Asserts that the JSON is equal to another JSON ignoring properties' order and formatting. |
-| `str?.shouldContainJsonKey("$.json.path")` | Asserts that the JSON contains a JSON path. |
-| `str?.shouldContainJsonKeyValue("$.json.path", value)` | Asserts that the JSON contains a JSON path with a specific `value`. |
-| `str?.shouldMatchJsonResource("/file.json")` | Asserts that the JSON is equal to the existing `/file.json` ignoring properties' order and formatting. |
+For example, the following two JSON strings would be considered equal:
 
+```json
+{
+   "name": "sam",
+   "location": "chicago",
+   "age" : 41
+}
+```
+
+and
+
+```json
+{ "age" : 41, "name": "sam", "location": "chicago" }
+```
+
+The inverse of this matcher is `shouldNotEqualJson` which will error if two JSON strings
+_are_ considered equal.
+
+### CompareMode
+
+`shouldEqualJson` supports a parameter called `CompareMode` which can be used to guide comparison of types that contain
+compatible values.
+
+By setting this to `CompareMode.Lenient`, types that can be coerced to match are considered equal. For example,
+the string value `"true"` and the boolean value `true` will be considered equal if compare mode is lenient.
+
+Similarly, the string value `"123"` and the number value `123` will match in lenient mode.
+
+For example:
+
+```kotlin
+val a = """ { "a": "true", "b": "123" } """
+val b = """ { "a": true, "b": 123 } """
+
+// this would pass
+a.shouldEqualJson(b, CompareOrder.Lenient)
+
+// this would fail
+a.shouldEqualJson(b)
+```
+
+:::note
+Longs and doubles will always attempt to match regardless of this setting.
+:::
+
+The default is `CompareMode.Strict` which will consider any values unequal if they have different types.
+
+### CompareOrder
+
+`shouldEqualJson` additionally supports a parameter called `CompareOrder` which can be used to force object comparision
+to consider field order. By default, the order of fields in an object does not matter, and so
+
+```json
+{ "a": "foo", "b": "bar" }
+```
+
+and
+
+```json
+{ "b": "bar", "a": "foo" }
+```
+
+would be considered equal. Setting this parameter to `CompareOrder.Strict` means that the above example would fail. For example:
+
+```kotlin
+val a = """ { "a": "foo", "b": "bar" } """
+val b = """ { "b": "bar", "a": "foo" } """
+
+// this would fail
+a.shouldEqualJson(b, CompareOrder.Strict)
+
+// this would pass
+a.shouldEqualJson(b)
+```
+
+Targets: **JVM**, **JS**
+
+## shouldContainJsonKey
+
+`json?.shouldContainJsonKey("$.json.path")` asserts that a JSON string contains the given JSON path.
+
+The inverse of this matcher is `shouldNotContainJsonKey` which will error if a JSON string _does_ contain the given JSON path.
+
+Targets: **JVM**
+
+## shouldContainJsonKeyValue
+
+`str?.shouldContainJsonKeyValue("$.json.path", value)` asserts that a JSON string contains a JSON path with a specific `value`.
+
+The inverse of this matcher is `shouldNotContainJsonKeyValue` which will error if a JSON string _does_ contain the given value at the given JSON path.
+
+Targets: **JVM**
+
+## shouldMatchJsonResource
+
+`json?.shouldContainJsonKey("$.json.path")` asserts that the JSON is equal to the existing `/file.json` ignoring properties' order and formatting.
+
+Targets: **JVM**
 
 :::note
-JSON matchers are built using the Jackson library
+JSON matchers on the JVM are built using the Jackson library.
 :::

documentation/docs/assertions/jsoup.md

@@ -1,6 +1,7 @@
 ---
 title: Jsoup Matchers
 slug: jsoup-matchers.html
+sidebar_label: Jsoup
 ---
 
 

documentation/docs/assertions/klock.md

@@ -1,6 +1,7 @@
 ---
 title: Klock Matchers
 slug: klock-matchers.html
+sidebar_label: Klock
 ---
 
 

documentation/docs/assertions/konform.md

@@ -1,6 +1,7 @@
 ---
 title: Konform Matchers
 slug: konform-matchers.html
+sidebar_label: Konform
 ---
 
 

documentation/docs/assertions/kotlinx-datetime.md

@@ -2,6 +2,7 @@
 id: kotlinx_datetime
 title: Kotlinx Datetime Matchers
 slug: kotlinx-datetime-matchers.html
+sidebar_label: Kotlinx Datetime
 ---
 
 

documentation/docs/assertions/ktor.md

@@ -2,6 +2,7 @@
 id: ktor
 title: Ktor Matchers
 slug: ktor-matchers.html
+sidebar_label: Ktor
 ---
 
 

documentation/docs/assertions/sql.md

@@ -2,5 +2,6 @@
 id: sql-matchers
 title: SQL Matchers
 slug: sql-matchers.html
+sidebar_label: SQL
 ---
 

documentation/sidebars.js

@@ -27,17 +27,17 @@ module.exports = {
          label: "Matcher Modules",
          collapsed: false,
          items: [
-            'assertions/android_matchers',
-            'assertions/arrow',
-            'assertions/compiler',
             'assertions/core',
             'assertions/json',
-            'assertions/jsoup',
-            'assertions/klock',
-            'assertions/konform',
-            'assertions/kotlinx_datetime',
             'assertions/ktor',
+            'assertions/android_matchers',
+            'assertions/kotlinx_datetime',
+            'assertions/arrow',
             'assertions/sql-matchers',
+            'assertions/konform',
+            'assertions/klock',
+            'assertions/compiler',
+            'assertions/jsoup',
          ]
       }
    ],