feat: adding JSON overview and Json configuration docs

[daniCsorbaJB]

This is the fifth part of the Kotlin Serialization rewrite task.

Related Youtrack ticket: KT-81979

[sandwwraith]

I see we can nicely add encodeToStream/decodeFromStream to the list here. IMO it's OK to add a separate page for them + Okio integration

[daniCsorbaJB]

yes it definitely fits neatly here 👍

• Use JVM streams with the encodeToStream() .decodeFromStream(), and .decodeToSequence() functions to work with JSON directly from input and output streams.

[sandwwraith]

Great. Oh, and Okio's encodeToSink/decodeFromSource can also go there

[sandwwraith]

We have a pair of new flags that aren't in docs yet: allowTrailingComma and allowComments. Can you take care of them, please? (they won't be experimental in next release)

[daniCsorbaJB]

Sure thing 👍

What do you think about placing it under Lenient parsing (it won't appear in the navigation, but if someone is looking for leniency, I'm pretty sure they would look for it there and will find it)

Something like:

Allow trailing commas

To allow trailing commas in JSON input, set the allowTrailingComma property to true:

// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
// Allows trailing commas in JSON objects and arrays
val format = Json { allowTrailingComma = true }

fun main() {
    val numbers = format.decodeFromString<List<Int>>(
        """
            [1, 2, 3,]
        """
    )
    println(numbers)
    // [1, 2, 3]
}
//sampleEnd

{kotlin-runnable="true"}

Allow comments in JSON

Use the allowComments property to allow comments in JSON input.
When this property is enabled, the parser accepts the following comment forms in the input:

• // line comments that end at a newline \n
• /* */ block comments

Nested block comments aren't supported

{style="note"}

Here's an example:

// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
// Allows comments in JSON input
val format = Json { allowComments = true }

fun main() {
    val numbers = format.decodeFromString<List<Int>>(
        """
            [
                // first element
                1,
                /* second element */
                2
            ]
        """
    )
    println(numbers)
    // [1, 2]
}
//sampleEnd

{kotlin-runnable="true"}

[sandwwraith]

What do you think about placing it under Lenient parsing (it won't appear in the navigation, but if someone is looking for leniency, I'm pretty sure they would look for it there and will find it)

I don't think so; they're not really related, as lenient in its current state is pretty exotic — not a lot of people have unquoted keys. Also, many people may not even know what this word means. So it's better to have trailing commas/comments with their own sections in the navigation

[sandwwraith]

Nested block comments aren't supported
{style="note"}

I think this info is insignificant here

[daniCsorbaJB]

removed it 👍