Fixed some typos in the basics chapter. (#1214)

Author: ianbrandt

docs/basic-serialization.md

@@ -33,10 +33,10 @@ This chapter shows the basic use of Kotlin Serialization and explains its core c
 ## Basics
 
 To convert an object tree to a string or to a sequence of bytes, it must come
-through two mutually intertwined processes. In the first step, an object is _serialized_ — 
-it is converted into a serial sequence of its constituting primitive values. This process is common for all 
+through two mutually intertwined processes. In the first step, an object is _serialized_—it 
+is converted into a serial sequence of its constituting primitive values. This process is common for all 
 data formats and its result depends on the object being serialized. A _serializer_ controls this process. 
-The second step is called _encoding_ — it is the conversion of the corresponding sequence of primitives into 
+The second step is called _encoding_—it is the conversion of the corresponding sequence of primitives into 
 the output format representation. An _encoder_ controls this process. Whenever the distinction is not important,
 both the terms of encoding and serialization are used interchangeably.
 
@@ -58,10 +58,9 @@ import kotlinx.serialization.json.*
 
 ### JSON encoding
 
-The whole process of converting data into a specific format is called _encoding_. For JSON we  
-encode data using the [Json.encodeToString][kotlinx.serialization.encodeToString] extension function. 
-It serializes the object
-that is passed as its parameter under the hood and encodes it to a JSON string.
+The whole process of converting data into a specific format is called _encoding_. For JSON we encode data 
+using the [Json.encodeToString][kotlinx.serialization.encodeToString] extension function. It serializes 
+the object that is passed as its parameter under the hood and encodes it to a JSON string.
 
 Let's start with a class describing a project and try to get its JSON representation.
 
@@ -85,7 +84,7 @@ Mark the class as @Serializable or provide the serializer explicitly.
 
 <!--- TEST LINES_START -->
 
-Serializable classes have to be explicitly marked. Kotlin serialization does not use reflection, 
+Serializable classes have to be explicitly marked. Kotlin Serialization does not use reflection, 
 so you cannot accidentally deserialize a class which was not supposed to be serializable. We fix it by
 adding the [`@Serializable`][Serializable] annotation.
 
@@ -101,7 +100,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-basic-02.kt).
 
-The `@Serializable` annotation instructs Kotlin Serialization plugin to automatically generate and hook 
+The `@Serializable` annotation instructs the Kotlin Serialization plugin to automatically generate and hook 
 up a _serializer_ for this class. Now the output of the example is the corresponding JSON.
 
 ```text
@@ -111,17 +110,16 @@ up a _serializer_ for this class. Now the output of the example is the correspon
 <!--- TEST -->    
 
 > There is a whole chapter about the [Serializers](serializers.md). For now, it is enough to know
-> that they are automatically generated by the Kotlin serialization plugin.                                 
+> that they are automatically generated by the Kotlin Serialization plugin.                                 
 
 ### JSON decoding
 
 The reverse process is called _decoding_. To decode a JSON string into an object, we'll 
 use the [Json.decodeFromString][kotlinx.serialization.decodeFromString] extension function. 
-To specify which type we want to get as a result, 
-we provide a type parameter to this function. 
+To specify which type we want to get as a result, we provide a type parameter to this function. 
 
 As we'll see later, serialization works with different kinds of classes. 
-Here we are marking our `Project` class as `data class` not because it is required, but because
+Here we are marking our `Project` class as a `data class`, not because it is required, but because
 we want to print its contents to verify how it decodes.
 
 ```kotlin
@@ -157,7 +155,7 @@ import kotlinx.serialization.json.*
 
 ### Backing fields are serialized
 
-Only class's properties with backing fields are serialized, so properties with getter/setter that don't
+Only a class's properties with backing fields are serialized, so properties with a getter/setter that don't
 have a backing field and delegated properties are not serialized, as the following example shows.
 
 ```kotlin        
@@ -182,7 +180,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-classes-01.kt).
 
-We can clearly see that only `name` and `stars` properties are present in the JSON output.
+We can clearly see that only the `name` and `stars` properties are present in the JSON output.
 
 ```text 
 {"name":"kotlinx.serialization","stars":9000}
@@ -192,8 +190,8 @@ We can clearly see that only `name` and `stars` properties are present in the JS
 
 ### Constructor properties requirement
 
-If we want to define the `Project` class so that it takes a path string and then 
-deconstructs them into the corresponding properties, then we might be tempted to write something like the code below.
+If we want to define the `Project` class so that it takes a path string, and then 
+deconstructs it into the corresponding properties, we might be tempted to write something like the code below.
 
 ```kotlin
 @Serializable 
@@ -205,9 +203,9 @@ class Project(path: String) {
 
 <!--- CLEAR -->
 
-This class does not compile, because `@Serializable` annotation requires that all parameters of the class primary
-constructor are properties. A simple workaround is to define a private primary constructor with class's
-properties and turn the constructor we wanted into the secondary one.
+This class does not compile because the `@Serializable` annotation requires that all parameters of the class's primary
+constructor be properties. A simple workaround is to define a private primary constructor with the class's
+properties, and turn the constructor we wanted into the secondary one.
 
 ```kotlin
 @Serializable 
@@ -222,7 +220,7 @@ class Project private constructor(val owner: String, val name: String) {
 }
 ```    
 
-Serialization works with private primary constructor and still serializes only backing fields.
+Serialization works with a private primary constructor, and still serializes only backing fields.
 
 ```kotlin
 fun main() {
@@ -244,7 +242,7 @@ This example produces the expected output.
 
 Another case where you might want to introduce a primary constructor parameter without a property is when you
 want to validate its value before storing it to a property. To make it serializable you shall replace it 
-with a property in the primary constructor and move validation to an `init { ... }` block.
+with a property in the primary constructor, and move the validation to an `init { ... }` block.
 
 ```kotlin
 @Serializable
@@ -269,7 +267,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-classes-03.kt).
 
-Running this code produces the exception.
+Running this code produces the exception:
 
 ```text 
 Exception in thread "main" java.lang.IllegalArgumentException: name cannot be empty
@@ -296,7 +294,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-classes-04.kt).
 
-It produces the exception.
+It produces the exception:
 
 ```text
 Exception in thread "main" kotlinx.serialization.MissingFieldException: Field 'language' is required, but it was missing
@@ -305,7 +303,7 @@ Exception in thread "main" kotlinx.serialization.MissingFieldException: Field 'l
 <!--- TEST LINES_START -->
 
 This problem can be fixed by adding a default value to the property, which automatically makes it optional
-for serialization:
+for serialization.
 
 ```kotlin
 @Serializable 
@@ -354,7 +352,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-classes-06.kt).
  
-Since `language` property was specified in the input, we don't see "Computing" string printed
+Since the `language` property was specified in the input, we don't see the "Computing" string printed
 in the output.
 
 ```text
@@ -366,7 +364,7 @@ Project(name=kotlinx.serialization, language=Kotlin)
 ### Required properties
 
 A property with a default value can be required in a serial format with the [`@Required`][Required] annotation.
-Let us change the previous example by marking `language` property as `@Required`.
+Let us change the previous example by marking the `language` property as `@Required`.
 
 ```kotlin
 @Serializable 
@@ -419,12 +417,12 @@ Use 'ignoreUnknownKeys = true' in 'Json {}' builder to ignore unknown keys.
 
 <!--- TEST LINES_START -->
 
-> 'ignoreUnknownKeys' feature is explained in the [Ignoring Unknown Keys section](json.md#ignoring-unknown-keys) section.
+> The 'ignoreUnknownKeys' feature is explained in the [Ignoring Unknown Keys section](json.md#ignoring-unknown-keys) section.
 
 ### Defaults are not encoded
 
-Default values are not encoded by default in JSON. This behavior is motivated by the fact that in most real-life scenarios,
-such configuration reduces visual clutter and saves amount of data being serialized. 
+Default values are not encoded by default in JSON. This behavior is motivated by the fact that in most real-life scenarios
+such configuration reduces visual clutter, and saves the amount of data being serialized. 
 
 ```kotlin
 @Serializable 
@@ -438,7 +436,7 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-classes-09.kt).
 
-It produces the following output, which does not have `language` property, because its value is equal to the default one.
+It produces the following output, which does not have the `language` property because its value is equal to the default one.
 
 ```text
 {"name":"kotlinx.serialization"}
@@ -450,7 +448,7 @@ It produces the following output, which does not have `language` property, becau
 
 ### Nullable properties
 
-Nullable properties are natively supported by Kotlin serialization.
+Nullable properties are natively supported by Kotlin Serialization.
 
 ```kotlin
 @Serializable
@@ -474,7 +472,7 @@ This example does not encode `null` in JSON because [Defaults are not encoded](#
 
 ### Type safety is enforced
 
-Kotlin serialization strongly enforces type safety of the Kotlin programming language. 
+Kotlin Serialization strongly enforces the type safety of the Kotlin programming language. 
 In particular, let us try to decode a `null` value from a JSON object into a non-nullable Kotlin property `language`.
 
 ```kotlin
@@ -531,14 +529,14 @@ When encoded to JSON it results in a nested JSON object.
 {"name":"kotlinx.serialization","owner":{"name":"kotlin"}}
 ```
 
-> References to non-serializable classes can be marked as [Transient properties](#transient-properties) or a
+> References to non-serializable classes can be marked as [Transient properties](#transient-properties), or a
 > custom serializer can be provided for them as shown in the [Serializers](serializers.md) chapter.  
 
 <!--- TEST -->
 
 ### No compression of repeated references
 
-Kotlin serialization is designed for encoding and decoding of plain data. It does not support reconstruction
+Kotlin Serialization is designed for encoding and decoding of plain data. It does not support reconstruction
 of arbitrary object graphs with repeated object references. For example, let us try to serialize an object
 that references the same `owner` instance twice.
 
@@ -564,22 +562,22 @@ We simply get the `owner` value encoded twice.
 {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"maintainer":{"name":"kotlin"}}
 ```       
 
-> Attempt to serialize a circular structure will end up with stack overflow. 
+> Attempt to serialize a circular structure will result in stack overflow. 
 > You can use the [Transient properties](#transient-properties) to exclude some references from serialization.
 
 <!--- TEST -->
 
 ### Generic classes
 
-Generic classes in Kotlin provide type-polymorphic behavior, which is enforced by Kotlin serialization at 
+Generic classes in Kotlin provide type-polymorphic behavior, which is enforced by Kotlin Serialization at 
 compile-time. For example, consider a generic serializable class `Box<T>`.
 
 ```kotlin
 @Serializable
 class Box<T>(val contents: T)
 ```                              
 
-The `Box<T>` class can be used with builtin types like `Int` as well as with user-defined types like `Project`.  
+The `Box<T>` class can be used with builtin types like `Int`, as well as with user-defined types like `Project`.  
 
 <!--- INCLUDE
 
@@ -610,14 +608,14 @@ The actual type that we get in JSON depends on the actual compile-time type para
 
 <!--- TEST -->
 
-If the actual generic type is not serializable, compile-time error will be produced.
+If the actual generic type is not serializable a compile-time error will be produced.
 
 ### Serial field names
 
 The names of the properties used in encoded representation, JSON in our examples, are the same as 
-their names in the source code by default. The name that is used for serialization is called a _serial name_ and
-can be changed using the [`@SerialName`][SerialName] annotation. For example, we can have a `language` property in the source,
-with an abbreviated serial name.
+their names in the source code by default. The name that is used for serialization is called a _serial name_, and
+can be changed using the [`@SerialName`][SerialName] annotation. For example, we can have a `language` property in 
+the source with an abbreviated serial name.
 
 ```kotlin
 @Serializable
@@ -657,4 +655,3 @@ The next chapter covers [Builtin classes](builtin-classes.md).
 <!--- MODULE /kotlinx-serialization-json -->
 <!--- INDEX kotlinx-serialization-json/kotlinx.serialization.json -->
 <!--- END -->
-