Clarify that Json.isLenient flag only affects invalid json such as unquoted strings and does not affect quoted values type mapping. (#2754)

Fixes #2749

Co-authored-by: Sergey Shanshin <[email protected]>

Author: sandwwraith

docs/json.md

@@ -122,13 +122,15 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-json-02.kt).
 
-You get the object, even though all keys of the source JSON, string, and enum values are unquoted, while an
-integer is quoted:
+You get the object, even though all keys of the source JSON, string and enum values are unquoted:
 
 ```text
 Project(name=kotlinx.serialization, status=SUPPORTED, votes=9000)
 ```
 
+> Note that parsing of quoted numbers or booleans such as `votes: "9000"` to `val votes: Int` is generally allowed by kotlinx.serialization
+> regardless of the `isLenient` flag, since such JSON is syntactically valid.
+
 <!--- TEST -->
 
 ### Ignoring unknown keys

formats/json/commonMain/src/kotlinx/serialization/json/Json.kt

@@ -418,6 +418,9 @@ public class JsonBuilder internal constructor(json: Json) {
      * Removes JSON specification restriction (RFC-4627) and makes parser
      * more liberal to the malformed input. In lenient mode, unquoted JSON keys and string values are allowed.
      *
+     * Example of invalid JSON that is accepted with this flag set:
+     * `{key: value}` can be parsed into `@Serializable class Data(val key: String)`.
+     *
      * Its relaxations can be expanded in the future, so that lenient parser becomes even more
      * permissive to invalid values in the input.
      *