Correcting typos and syntax inconsistencies for circe exercises

src/main/scala/circelib/EncodingDecodingSection.scala

@@ -21,7 +21,7 @@ object EncodingDecodingSection
 
   /**
    * Circe uses `Encoder` and `Decoder` type classes for encoding and decoding. An `Encoder[A]` instance provides a function
-   * that will convert any `A` to a `Json` and a `Decoder[A]` takes a `Json` value to either an exception or an `A`.circe provides
+   * that will convert any `A` to a `Json` and a `Decoder[A]` takes a `Json` value to either an exception or an `A`. Circe provides
    * implicit instances of these type classes for many types from the Scala standard library, including `Int`, `String`, and others.
    * It also provides instances for `List[A]`, `Option[A]`, and other generic types, but only if `A` has an `Encoder` instance.
    *
@@ -39,7 +39,7 @@ object EncodingDecodingSection
    *   // ]
    * }}}
    *
-   * Use the `.as` syntax for decoding data from Json:
+   * Use the `.as` syntax for decoding data from `Json`:
    *
    * {{{
    *   intsJson.as[List[Int]]
@@ -52,7 +52,7 @@ object EncodingDecodingSection
    *   import io.circe.parser.decode
    * }}}
    *
-   *  Try your answer for this exercercises
+   *  Let's decode a JSON String:
    */
   def decodeJson(res0: Boolean, res1: Either[String, List[Int]]): Unit = {
     val decodeList = decode[List[Int]]("[1, 2, 3]")
@@ -65,7 +65,7 @@ object EncodingDecodingSection
   /**
    * ==Semi-automatic derivation
    *
-   * Sometimes it´ convenient to have an `Encoder` or `Decoder` defined in your code, and '''semi-automatic''' derivation can help. You´d write:
+   * Sometimes it's convenient to have an `Encoder` or `Decoder` defined in your code, and '''semi-automatic''' derivation can help. You´d write:
    *
    * {{{
    *   import io.circe._, io.circe.generic.semiauto._
@@ -104,7 +104,7 @@ object EncodingDecodingSection
    *
    *  ==forProductN helper methods==
    *
-   * It´s also possible to construct encoders and decoders for case class-like types in a relatively boilerplate-free way without generic derivation:
+   * It's also possible to construct encoders and decoders for case class-like types in a relatively boilerplate-free way without generic derivation:
    * {{{
    *   case class User(id: Long, firstName: String, lastName: String)
    *
@@ -125,12 +125,10 @@ object EncodingDecodingSection
    *
    * ==Fully automatic derivation==
    *
-   *  It is also possible to derive `Encoder` and `Decoder`s for many types with no boilerplate at all.
-   *  Circe uses [[https://github.com/milessabin/shapeless shapeles]] to automatically derive the necessary type class instances:
+   *  It is also possible to derive an `Encoder` and `Decoder` for many types with no boilerplate at all.
+   *  Circe uses [[https://github.com/milessabin/shapeless shapeless]] to automatically derive the necessary type class instances:
    *
-   *  import io.circe.generic.auto._
-   *
-   *  Let´s see what happens when we create a Json with derived fields
+   *  Let´s see what happens when we create a `Json` with derived fields
    *
    *  For this example we need to import `io.circe.generic.auto._`
    */
@@ -205,7 +203,7 @@ object EncodingDecodingSection
    *   json.as[Map[Foo, Int]]
    * }}}
    *
-   * Let´s try your answer for this example:
+   * What would be returned as a result of decoding and traversing the returned `Map`:
    */
   def mapJson(res0: Either[String, Int]): Unit =
     json.hcursor.downField("hello").as[Int] should be(res0)

src/main/scala/circelib/JsonSection.scala

@@ -16,16 +16,16 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
 
   import JsonHelpers._
 
-  /** Json is the circe data type representing a Json object. It's very useful to be familiar with this data type since
+  /** `Json` is the circe data type representing a JSON object. It's very useful to be familiar with this data type since
    * it's how circe models the base type we want to address.
    *
-   * To begin, let's briefly talk about the shape of every Json object. It's basically semi-structured data built on
+   * To begin, let's briefly talk about the shape of every `Json` object. It's basically semi-structured data built on
    * top of key-value pairs. These key-value pairs have a specific shape:
    *   - keys are strings.
    *   - values can be multiple types.
    *
-   * Next, to model a real json object, we need to support different data types in the value field. For this purpose,
-   * we have different available methods so we can create a Json object from different source data types. Some examples
+   * Next, to model a real JSON object, we need to support different data types in the value field. For this purpose,
+   * we have different available methods so we can create a `Json` object from different source data types. Some examples
    * of these methods are `fromString`, `fromBoolean`, `fromDouble` and so on. For further details about all possible
    * methods, see the [[http://circe.github.io/circe/api/io/circe/Json$.html Scala docs]].
    *
@@ -60,7 +60,7 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
    * }}}
    *
    *
-   * In addition, there are a few other methods that allow you to convert a Json object to a String.
+   * In addition, there are a few other methods that allow you to convert a `Json` object to a `String`.
    *
    * {{{
    *
@@ -91,12 +91,12 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
    *
    * }}}
    *
-   * What would be the string output for our jsonFromFields value?
+   * What would be the string output for our `jsonFromFields` value?
    */
   def jsonToString(res0: String) =
     jsonFromFields.noSpaces should be(res0)
 
-  /** Let's see how we can use these methods to create custom Jsons that represents specific Json strings.
+  /** Let's see how we can use these methods to create custom `Json`s that represents specific JSON strings.
    */
   def jsonObject(res0: Json, res1: (String, Json), res2: (String, Json), res3: Json) = {
 
@@ -109,11 +109,11 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
 
   }
 
-  /** Furthemore, there are some other methods that allow you to deal with Json objects and apply transformation. We
-   * can use them to modify or apply any changes to a given Json object in a simpler way, as if we we're dealing with it
+  /** Furthemore, there are some other methods that allow you to deal with `Json` objects and apply transformation. We
+   * can use them to modify or apply any changes to a given `Json` object in a simpler way, as if we we're dealing with it
    * manually.
    *
-   * We are going to start with this Json array:
+   * We are going to start with this `Json` array:
    *
    * {{{
    *   val jsonArray: Json = Json.fromValues(List(
@@ -126,7 +126,7 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
    *
    * }}}
    *
-   * Finally, we have a transformJson method:
+   * Finally, we have a `transformJson` method:
    *
    * {{{
    *   def transformJson(jsonArray: Json): Json =
@@ -135,7 +135,7 @@ object JsonSection extends FlatSpec with Matchers with definitions.Section {
    *     }
    * }}}
    *
-   * So, with these in mind, what should be the result if we apply our transformJson function to our jsonArray value?
+   * So, with these in mind, what should be the result if we apply our `transformJson` function to our `jsonArray` value?
    *
    */
   def jsonClass(res0: String) =

src/main/scala/circelib/OpticsSection.scala

@@ -81,7 +81,7 @@ object OpticsSection extends FlatSpec with Matchers with org.scalaexercises.defi
    *
    * }}}
    *
-   * Now is your turn, let´ try your answer:
+   * Now is your turn, let´s try your answer:
    */
   def checkTraversingOptics(res0: Option[String]): Unit = {
     val address: Option[String] = _address.getOption(json)
@@ -144,7 +144,7 @@ object OpticsSection extends FlatSpec with Matchers with org.scalaexercises.defi
    * `JsonPath` relies on a feature of Scala called `Dynamic`. Using `Dynamic` you can call methods that don´t actually exist.
    * When you do so, the `selectDynamic` method is called, and the name of the method you wanted to call is passed as an argument.
    *
-   * The use of Dynamic means that your code is not "typo-safe". So be careful when you typing
+   * The use of `Dynamic` means that your code is not "typo-safe". So be careful when you are typing
    *
    * {{{
    *   val doubleQuantities: Json => Json =
@@ -153,7 +153,7 @@ object OpticsSection extends FlatSpec with Matchers with org.scalaexercises.defi
    *   val modifiedJson = doubleQuantities(json)
    * }}}
    *
-   * Let´s see the result for the last afirmation
+   * Let´s see the result for the last affirmation
    */
   def modifyingJsonDynamic(res0: Boolean): Unit = {
     val modifiedQuantitiesDynamic: List[Int] =

src/main/scala/circelib/TraversingSection.scala

@@ -72,7 +72,7 @@ object TraversingSection
   /**
    * You can also move to a side of an Array field.
    *
-   * Try your answer for this last example
+   * What would the result be when traversing through the array?
    */
   def moveFocus3(res0: Either[String, String]): Unit = {
     val secondQux: Decoder.Result[String] =
@@ -84,17 +84,17 @@ object TraversingSection
   /**
    * ==Transforming data==
    *
-   * In this section we are gona learn how to use a cursor to modify JSON
+   * In this section we are going to learn how to use a cursor to modify JSON
    *
-   * Circle has three slightly different cursor implementations:
+   * Circe has three slightly different cursor implementations:
    *
    * `Cursor` provides functionality for moving around a tree and making modifications.
    *
    * `HCursor` tracks the history of operations performed. This can be used to provide useful error messages when something goes wrong.
    *
    * `ACursor` also tracks history, but represents the possibility of failure (e.g. calling `downField` on a field that doesn’t exist.
    *
-   * Pay attention because we are gonna use a `.mapString` this time.
+   * Pay attention because we are going to use a `.mapString` this time.
    *
    * {{{
    *   val reversedNameCursor: ACursor =