tweak docs

Author: jillesvangurp

README.md

@@ -3,26 +3,32 @@
 [![Process Pull Request](https://github.com/jillesvangurp/json-dsl/actions/workflows/pr_master.yaml/badge.svg)](https://github.com/jillesvangurp/json-dsl/actions/workflows/pr_master.yaml)
 
 JsonDsl is a multi platform kotlin library that helps you build Kotlin DSLs for JSON and YAML dialects. 
-The DSLs are easy to extend with custom fields by users via a MutableMap.
+DSLs made with this library are easy to extend with custom fields by users via a MutableMap.
 
-A DSL (Domain Specific Language) differs from General Purpose Languages, such as Kotlin, in that a DSL is intended to program or drive a tool or framework for some domain or API. Kotlin like several other languages is suitable for creating internal DSLs that (ab)use the syntax of the host language to implement a DSL.
+# About DSLs
 
-## The problem
+A Domain Specific Language (DSL) is a language that is intended to allow users to program or specify things in language that closely matches their domain. They are popular for configuration files, for use with certain frameworks or tools, and there are a lot of niche tools, frameworks, and other software packages out there that implement them. 
 
-Of course, creating model classes for your json domain model and annotating them with annotations for e.g. `kotlinx.serialization` is a valid way to start creating a DSL for your JSON or YAML dialect of choice.
+Some general purpose languages have a syntax that makes it easy to (ab)use their features to do something similar. Lisp and Ruby are a good example of languages that have historically been used for this. Like those languages, Kotlin includes a few features that enable this. Which makes Kotlin very well suited for implementing all sorts of DSLs.
 
-However, this has some limitations. What if your JSON dialect evolves and somebody adds some new features? Unless you change your model class, it would not be possible to access such new features via the Kotlin DSL. Or what if your JSON dialect is vast and complicated. Do you have to support all of it? How do you decide what to allow and not allow in your Kotlin DSL.
+There are Kotlin DSLs for all sorts of things. A popular example is the HTML DSL that comes with things like Ktor and kotlin-js. Spring bundles a lot of Kotlin DSLs for it's Java framework that make using that a lot nicer than from Java. There are lots of examples.
 
-This library started out as few classes in my [kt-search](https://github.com/jillesvangurp/kt-search) project, which implements an Elasticsearch and Opensearch client. Elasticsearch has several JSON dialects that are used for querying, defining index mappings, settings, and a few other things. Especially the query language has a large number of features and is constantly evolving. 
+## Making easy to extend Kotlin DSLs for JSON/YAML dialects
+
+Of course, creating model classes for your JSON domain model and annotating thosre with annotations for e.g. `kotlinx.serialization`, `jackson`, etc. is a perfectly valid way to start creating a DSL for your JSON or YAML dialect of choice.
+
+However, using JSON frameworks like that have some limitations. What if your JSON dialect evolves and somebody adds some new features? Unless you change your model class, it would not be possible to access such new features via the Kotlin DSL. Or what if your JSON dialect is vast and complicated. Do you have to support all of its features? How do you decide what to allow and not allow in your Kotlin DSL.
+
+This library started out as few classes in my [kt-search](https://github.com/jillesvangurp/kt-search) project. Kt-search implements a client library for Elasticsearch and Opensearch. Elasticsearch has several JSON dialects that are used for querying, defining index mappings, settings, and a few other things. Especially the query language has a large number of features and is constantly evolving. 
 
 Not only do I have to worry about implementing each and every little feature these DSLs have and keeping up with upstream additions to OpenSearch and Elasticsearch. I also have to worry about supporting query and mapping features added via custom plugins. This is very challenging. And it was the main reason I created json-dsl: so I don't have to keep up.
 
 ## Strongly typed and Flexible
 
-The key feature in json-dsl is that it uses a `MutableMap` for storing property values. This enables you to define classes with properties that delegate storing their value to this map. For anything that your
-classes don't implement, the user can always write to the map directly using a simple `put`.
+The key feature in json-dsl is that it uses a `MutableMap` and property delegation for implementing DSL classes. This simple approach enables you to define classes with properties that delegate storing their value to this map. For anything that your
+classes don't implement, the user can simply modify the underlying map directly using a simple `put`.
 
-This gives users a nice fallback for things your DSL classes don't implement and it relieves Kotlin DSL implementors from having to provide support for every new feature the upstream JSON dialect has or adds over time. You can provide a decent experience for your users with minimal effort. And you users can always work around whatever you did not implement.
+This simple approach gives users a nice fallback for things your DSL classes don't implement and it relieves Kotlin DSL creators from having to provide support for every new feature the upstream JSON dialect has or adds over time. You can provide a decent experience for your users with minimal effort. And you users can always work around whatever you did not implement.
 
 With kt-search, I simply focus on supporting all the commonly used, and some less commonly used things in the Elastic DSLs. But for everything else, I just rely on letting the user modify the underlying map themselves. A lot of pull requests I get on this project are people adding features they need in the DSLs. So, over time, feature support has gotten more comprehensive.
 
@@ -49,7 +55,7 @@ And then you can add the dependency:
     implementation("com.jillesvangurp:json-dsl:3.x.y")
 ```
 
-If you were using json-dsl via kt-search before, you can update simply by bumping the version of json-dsl to 3.0. 2.x got released along with kt-search and has now been removed.
+If you were using json-dsl via kt-search before, you can update simply by bumping the version of json-dsl to 3.0. Previously, 2.x was released along with kt-search and has now been removed from that project.
 
 
 ## Examples
@@ -97,13 +103,11 @@ There is also a YAML serializer. More on that below.
 ### Common Kotlin Types
 
 JSON is a fairly simple data format. It has numbers, booleans, strings, lists and dictionaries. And null
-values. 
-
-Kotlin has a bit richer type system and mapping that to JSON is key to providing rich Kotlin DSL.                
+values.  Kotlin has a bit richer type system and mapping that to JSON is key to providing rich Kotlin DSL.                
 
 JsonDsl does a best effort to do map Kotlin types correctly to the intended JSON equivalent. 
 
-It understands all the primitives, Maps and Lists. But also Arrays, Sets, Sequences.                
+It understands all the primitives, Maps and Lists. But also Arrays, Sets, Sequences, etc.                
 And of course other JsonDsl classes, so you can nest them.  And it falls back to using 
 `toString()` for everything else.              
 
@@ -133,14 +137,14 @@ MyDsl().apply {
   idontknow = mapOf(
     "arrays" to arrayOf(
       1, 2, "3", 4.0,
-      mapOf("this" to "is valid JSON")
+      mapOf("this" to "is valid JSON"), "mixing types is allowed in JSON"
     ),
     "sequences" to sequenceOf(1,"2",3.0)
   )
 }
 ```
 
-This does the right things with all the Kotlin types, including `Any`:
+This does the right things with all the used Kotlin types, including `Any`:
 
 ```json
 {
@@ -166,7 +170,8 @@ This does the right things with all the Kotlin types, including `Any`:
       4.0, 
       {
         "this": "is valid JSON"
-      }
+      }, 
+      "mixing types is allowed in JSON"
     ],
     "sequences": [
       1, 
@@ -192,18 +197,21 @@ MyDsl().apply {
   // nicely typed.
   foo = "bar"
 
+  // but we never defined a bar property
   this["bar"] = "foo"
-  this["going_off_script"] = listOf(
+  // or this ...
+  this["whatever"] = listOf(
     MyDsl().apply {
-      this["anything"] = "is possible"
+      this["you"] = "can add anything you want"
     },
     42
   )
+
+  // RawJson is a Kotlin value class
   this["inline_json"] = RawJson("""
     {
       "if":"you need to",
-      "you":"can even add json in string form",
-      "RawJson":"is a value class"
+      "you":"can even add json in string form",               
     }
   """.trimIndent())
 }
@@ -213,40 +221,41 @@ MyDsl().apply {
 {
   "foo": "bar",
   "bar": "foo",
-  "going_off_script": [
+  "whatever": [
     {
-      "anything": "is possible"
+      "you": "can add anything you want"
     }, 
     42
   ],
   "inline_json": {
     "if":"you need to",
-    "you":"can even add json in string form",
-    "RawJson":"is a value class"
+    "you":"can even add json in string form",                           
 }
 }
 ```
 
 ### snake_casing, custom names, defaults
 
-A lot of JSON dialects use snake cased dictionary keys. Kotlin of course uses 
+A lot of JSON dialects use snake cased field names. Kotlin of course uses 
 camel case for its identifiers and it has certain things that you can't redefine.
-
 Like the `size` property on `Map`, which is implemented by JsonDsl; or certain keywords.
 
 ```kotlin
 class MyDsl : JsonDsl(
+  // this will snake case all the names
   namingConvention = PropertyNamingConvention.ConvertToSnakeCase
 ) {
-  // this will be snake cased
+  // -> camel_case
   var camelCase by property<Boolean>()
+  // unfortunately Map defines a size val already
   var mySize by property<Int>(
     customPropertyName = "size"
   )
+  // val is a keyword in Kotlin
   var myVal by property<String>(
     customPropertyName = "val"
   )
-  // explicitly set name and provide a default
+  // Kotlin has default values, JSON does not.
   var m by property(
     customPropertyName = "meaning_of_life",
     defaultValue = 42
@@ -271,11 +280,11 @@ MyDsl().apply {
 
 ### Custom values
 
-Sometimes you might want to have the serialized version of a value be different
+Sometimes you want to have the serialized version of a value be different
 from the kotlin type that you are using. For this we have added the 
 CustomValue interface.
 
-A simple use case for this could be Enums:
+A simple use case for this could be Enums:                                
 
 ```kotlin
 enum class Grades(override val value: Double) : CustomValue<Double> {
@@ -560,15 +569,15 @@ reference for how to use JsonDsl.
 
 ## Multi platform
 
-This is a Kotlin multi platform library that should work on most  kotlin platforms (jvm, js, ios, android, etc). Wasm will be added later, after Kotlin 2.0 stabilizes.
+This is a Kotlin multi platform library that should work on most  kotlin platforms (jvm, js, ios, wasm, linux/windows/mac native, android, etc).
 
-My intention is to keep this code very portable and not introduce any dependencies other than the Kotlin standard library.
+My intention is to keep this code very portable and lightweight and not introduce any dependencies other than the Kotlin standard library. 
 
 ## Development and stability
 
 Before I extracted it from there, this library was part of [kt-search](https://github.com/jillesvangurp/kt-search), which has been out there for several years and  has a steadily growing user base. So, even though this library is relatively new, the code base has been stable and actively used for several years.
 
-Other than cleaning the code a bit up for public use, there were no compatibility breaking changes. This means I want to keep the API for json-dsl stable and will not make any major changes unless there is a really good reason. 
+Other than cleaning the code a bit up for public use, there were no compatibility breaking changes. I want to keep the API for json-dsl stable and will not make any major changes unless there is a really good reason. 
 
 This also means there won't be a lot of commits or updates since things are stable and pretty much working as intended. And because I have a few users of kt-search, I also don't want to burden them with compatibility breaking changes. Unless somebody finds a bug or asks for reasonable changes, the only changes likely to happen will be occasional dependency updates.
 

src/jvmTest/kotlin/com/jillesvangurp/jsondsl/readme/ReadmeGenerationTest.kt

@@ -85,13 +85,11 @@ val readmeMd = sourceGitRepository.md {
         subSection("Common Kotlin Types") {
             +"""
                 JSON is a fairly simple data format. It has numbers, booleans, strings, lists and dictionaries. And null
-                values. 
-                
-                Kotlin has a bit richer type system and mapping that to JSON is key to providing rich Kotlin DSL.                
+                values.  Kotlin has a bit richer type system and mapping that to JSON is key to providing rich Kotlin DSL.                
                 
                 JsonDsl does a best effort to do map Kotlin types correctly to the intended JSON equivalent. 
                            
-                It understands all the primitives, Maps and Lists. But also Arrays, Sets, Sequences.                
+                It understands all the primitives, Maps and Lists. But also Arrays, Sets, Sequences, etc.                
                 And of course other JsonDsl classes, so you can nest them.  And it falls back to using 
                 `toString()` for everything else.              
             """.trimIndent()
@@ -122,14 +120,14 @@ val readmeMd = sourceGitRepository.md {
                     idontknow = mapOf(
                         "arrays" to arrayOf(
                             1, 2, "3", 4.0,
-                            mapOf("this" to "is valid JSON")
+                            mapOf("this" to "is valid JSON"), "mixing types is allowed in JSON"
                         ),
                         "sequences" to sequenceOf(1,"2",3.0)
                     )
                 }
             }.result.getOrThrow()!!.let {
                 +"""
-                    This does the right things with all the Kotlin types, including `Any`:
+                    This does the right things with all the used Kotlin types, including `Any`:
                 """.trimIndent()
                 mdCodeBlock(it.json(true), type = "json")
             }
@@ -149,18 +147,21 @@ val readmeMd = sourceGitRepository.md {
                     // nicely typed.
                     foo = "bar"
 
+                    // but we never defined a bar property
                     this["bar"] = "foo"
-                    this["going_off_script"] = listOf(
+                    // or this ...
+                    this["whatever"] = listOf(
                         MyDsl().apply {
-                            this["anything"] = "is possible"
+                            this["you"] = "can add anything you want"
                         },
                         42
                     )
+
+                    // RawJson is a Kotlin value class
                     this["inline_json"] = RawJson("""
                         {
                             "if":"you need to",
-                            "you":"can even add json in string form",
-                            "RawJson":"is a value class"
+                            "you":"can even add json in string form",                           
                         }
                     """.trimIndent())
                 }
@@ -170,26 +171,28 @@ val readmeMd = sourceGitRepository.md {
         }
         subSection("snake_casing, custom names, defaults") {
             +"""
-                A lot of JSON dialects use snake cased dictionary keys. Kotlin of course uses 
+                A lot of JSON dialects use snake cased field names. Kotlin of course uses 
                 camel case for its identifiers and it has certain things that you can't redefine.
-                
                 Like the `size` property on `Map`, which is implemented by JsonDsl; or certain keywords.
                 
             """.trimIndent()
 
             example {
                 class MyDsl : JsonDsl(
+                    // this will snake case all the names
                     namingConvention = PropertyNamingConvention.ConvertToSnakeCase
                 ) {
-                    // this will be snake cased
+                    // -> camel_case
                     var camelCase by property<Boolean>()
+                    // unfortunately Map defines a size val already
                     var mySize by property<Int>(
                         customPropertyName = "size"
                     )
+                    // val is a keyword in Kotlin
                     var myVal by property<String>(
                         customPropertyName = "val"
                     )
-                    // explicitly set name and provide a default
+                    // Kotlin has default values, JSON does not.
                     var m by property(
                         customPropertyName = "meaning_of_life",
                         defaultValue = 42
@@ -207,12 +210,11 @@ val readmeMd = sourceGitRepository.md {
         }
         subSection("Custom values") {
             +"""
-                Sometimes you might want to have the serialized version of a value be different
+                Sometimes you want to have the serialized version of a value be different
                 from the kotlin type that you are using. For this we have added the 
                 CustomValue interface.
                 
-                A simple use case for this could be Enums:
-                                
+                A simple use case for this could be Enums:                                
             """.trimIndent()
 
             exampleFromSnippet(ReadmeGenerationTest::class,"grades-enum")