Text tweaks covering most of the tutorial

src/main/scala/stdlib/Asserts.scala

@@ -36,13 +36,13 @@ object Asserts extends FlatSpec with Matchers with org.scalaexercises.definition
     * result shouldBe 3       // cannot customize equality, so fastest to compile, no parentheses required
     * }}}
     *
-    * Come on, your turn: true and false values can be compared with should matchers
+    * Come on, your turn: true and false values can be compared with should matchers:
     */
   def scalaTestAsserts(res0: Boolean) {
     true should be(res0)
   }
 
-  /** Booleans in asserts can test equality.
+  /** Booleans in asserts can test equality:
     */
   def booleanAsserts(res0: Int) {
     val v1 = 4
@@ -51,7 +51,7 @@ object Asserts extends FlatSpec with Matchers with org.scalaexercises.definition
     /** `shouldEqual` is an assertion. It is from ScalaTest, not from the Scala language. */
   }
 
-  /** Sometimes we expect you to fill in the values
+  /** Sometimes we expect you to fill in the values:
     */
   def valuesAsserts(res0: Int) {
     assert(res0 == 1 + 1)

src/main/scala/stdlib/ByNameParameter.scala

@@ -6,7 +6,7 @@ import org.scalatest._
   */
 object ByNameParameter extends FlatSpec with Matchers with org.scalaexercises.definitions.Section {
 
-  /** `() => Int` is a Function type that takes a `Unit` type. `Unit` is known as `void` to a Java programmer. The function returns an `Int`. You can place this as a method parameter so that you can you use it as a block, but still it doesn't look quite right.
+  /** `() => Int` is a Function type that takes a `Unit` type. `Unit` is known as `void` to a Java programmer. The function returns an `Int`. You can place this as a method parameter so that you can you use it as a block, but still it doesn't look quite right:
     */
   def takesUnitByNameParameter(res0: Either[Throwable, Int]) {
     def calc(x: () ⇒ Int): Either[Throwable, Int] = {
@@ -24,7 +24,7 @@ object ByNameParameter extends FlatSpec with Matchers with org.scalaexercises.de
     y should be(res0)
   }
 
-  /** A by-name parameter does the same thing as the previous koan but there is no need to explicitly handle `Unit` or `()`. This is used extensively in scala to create blocks.
+  /** A by-name parameter does the same thing as the previous koan but there is no need to explicitly handle `Unit` or `()`. This is used extensively in Scala to create blocks:
     */
   def byNameParameter(res0: Either[Throwable, Int]) {
     def calc(x: ⇒ Int): Either[Throwable, Int] = {
@@ -46,7 +46,7 @@ object ByNameParameter extends FlatSpec with Matchers with org.scalaexercises.de
     y should be(res0)
   }
 
-  /** By name parameters can also be used with an *Object* and apply to make interesting block-like calls
+  /** By name parameters can also be used with `object` and `apply` to make interesting block-like calls:
     */
   def withApplyByNameParameter(res0: String) {
     object PigLatinizer {

src/main/scala/stdlib/CaseClasses.scala

@@ -8,7 +8,7 @@ object CaseClasses extends FlatSpec with Matchers with org.scalaexercises.defini
 
   /** Scala supports the notion of ''case classes''. Case classes are regular classes which export their constructor parameters and which provide a recursive decomposition mechanism via pattern matching.
     *
-    * Here is an example for a class hierarchy which consists of an abstract super class `Term` and three concrete case classes `Var`, `Fun`, and `App`.
+    * Here is an example for a class hierarchy which consists of an abstract superclass `Term` and three concrete case classes `Var`, `Fun`, and `App`:
     *
     * {{{
     * abstract class Term
@@ -32,7 +32,7 @@ object CaseClasses extends FlatSpec with Matchers with org.scalaexercises.defini
     * println(x.name)
     * }}}
     *
-    * For every case class the Scala compiler generates `equals` method which implements structural equality and a`toString` method. For instance:
+    * For every case class the Scala compiler generates an `equals` method which implements structural equality and a `toString` method. For instance,
     *
     * {{{
     * val x1 = Var("x")
@@ -218,7 +218,7 @@ object CaseClasses extends FlatSpec with Matchers with org.scalaexercises.defini
     parts._4 should be(res3)
   }
 
-  /** Case classes are Serializable
+  /** Case classes are `Serializable`:
     */
   def serializableCaseClasses(res0: Boolean, res1: Boolean) {
     case class PersonCC(firstName: String, lastName: String)

src/main/scala/stdlib/Classes.scala

@@ -14,7 +14,7 @@ object Classes extends FlatSpec with Matchers with org.scalaexercises.definition
     * override def toString(): String = "(" + x + ", " + y + ")"
     * }
     * }}}
-    * The class defines two variables `x` and `y` and one method: `toString`.
+    * The class defines two variables `x` and `y` and one method `toString`.
     *
     * Classes in Scala are parameterized with constructor arguments. The code above defines two constructor arguments, `x` and `y`; they are both visible in the whole body of the class. In our example they are used to implement `toString`.
     *
@@ -31,7 +31,7 @@ object Classes extends FlatSpec with Matchers with org.scalaexercises.definition
     *
     * The program defines an executable application `Classes` in the form of a top-level singleton object with a `main` method. The `main` method creates a new `Point` and stores it in value `pt`.
     *
-    * This also demonstrates the use of value parameters in ClassWithValParameter(val name: String), which automatically creates an internal property (val name: String) in the class.
+    * This also demonstrates the use of value parameters in `ClassWithValParameter(val name: String)`, which automatically creates an internal property `val name: String` in the class:
     *
     */
   def classWithValParameterClasses(res0: String) {

src/main/scala/stdlib/EmptyValues.scala

@@ -17,7 +17,7 @@ object EmptyValues extends FlatSpec with Matchers with org.scalaexercises.defini
     *
     * ==Nothing==
     *
-    * [[http://www.scala-lang.org/api/current/index.html#scala.Nothing Nothing]] is a trait that is guaranteed to have _zero_ instances. It is a subtype of all other types. It has two main reasons for existing: to provide a return type for methods that **never** return normally (i.e. a method that always throws an exception). The other reason is to provide a type for Nil (explained below).
+    * [[http://www.scala-lang.org/api/current/index.html#scala.Nothing Nothing]] is a trait that is guaranteed to have zero instances. It is a subtype of all other types. It has two main reasons for existing: to provide a return type for methods that never return normally (i.e. a method that always throws an exception). The other reason is to provide a type for Nil (explained below).
     *
     * ==Unit==
     *
@@ -47,41 +47,41 @@ object EmptyValues extends FlatSpec with Matchers with org.scalaexercises.defini
     None eq None shouldBe res0
   }
 
-  /** `None` can be converted to a *String*:
+  /** `None` can be converted to a String:
     */
   def noneToStringEmptyValues(res0: String) {
     assert(None.toString === res0)
   }
 
-  /** `None` can be converted to an empty list
+  /** `None` can be converted to an empty list:
     */
   def noneToListEmptyValues(res0: Boolean) {
     None.toList === Nil shouldBe res0
   }
 
-  /** `None` is considered empty
+  /** `None` is considered empty:
     */
   def noneAsEmptyEmptyValues(res0: Boolean) {
     assert(None.isEmpty === res0)
   }
 
-  /** `None` can be cast `Any`, `AnyRef` or `AnyVal`
+  /** `None` can be cast to `Any`, `AnyRef` or `AnyVal`:
     */
   def noneToAnyEmptyValues(res0: Boolean, res1: Boolean, res2: Boolean) {
     None.asInstanceOf[Any] === None shouldBe res0
     None.asInstanceOf[AnyRef] === None shouldBe res1
     None.asInstanceOf[AnyVal] === None shouldBe res2
   }
 
-  /** `None` can be used with `Option` instead of null references
+  /** `None` can be used with `Option` instead of null references:
     */
   def noneWithOptionEmptyValues(res0: Boolean, res1: Option[String]) {
     val optional: Option[String] = None
     assert(optional.isEmpty === res0)
     assert(optional === res1)
   }
 
-  /** `Some` is the opposite of `None` for `Option` types
+  /** `Some` is the opposite of `None` for `Option` types:
     */
   def someAgainstNoneEmptyValues(res0: Boolean, res1: Boolean) {
     val optional: Option[String] = Some("Some Value")

src/main/scala/stdlib/Extractors.scala

@@ -25,8 +25,8 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     *
     * There are two syntactic conventions at work here:
     *
-    * - The pattern `case Twice(n)` will cause an invocation of `Twice.unapply`, which is used to match even number; the return value of the `unapply` signals whether the argument has matched or not, and any sub-values that can be used for further matching. Here, the sub-value is `z/2`
-    * - The `apply` method is not necessary for pattern matching. It is only used to mimick a constructor. `val x = Twice(21)` expands to `val x = Twice.apply(21)`.
+    *  - The pattern `case Twice(n)` will cause an invocation of `Twice.unapply`, which is used to match even number; the return value of the `unapply` signals whether the argument has matched or not, and any sub-values that can be used for further matching. Here, the sub-value is `z/2`
+    *  - The `apply` method is not necessary for pattern matching. It is only used to mimick a constructor. `val x = Twice(21)` expands to `val x = Twice.apply(21)`.
     *
     * The code in the preceding example would be expanded as follows:
     *
@@ -38,9 +38,9 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     * }}}
     * The return type of an `unapply` should be chosen as follows:
     *
-    * - If it is just a test, return a `Boolean`. For instance `case even()`
-    * - If it returns a single sub-value of type `T`, return a `Option[T]`
-    * - If you want to return several sub-values `T1,...,Tn`, group them in an optional tuple `Option[(T1,...,Tn)]`.
+    *  - If it is just a test, return a `Boolean`. For instance `case even()`
+    *  - If it returns a single sub-value of type `T`, return a `Option[T]`
+    *  - If you want to return several sub-values `T1,...,Tn`, group them in an optional tuple `Option[(T1,...,Tn)]`.
     *
     * Sometimes, the number of sub-values is fixed and we would like to return a sequence. For this reason, you can also define patterns through `unapplySeq`. The last sub-value type `Tn` has to be `Seq[S]`. This mechanism is used for instance in pattern `case List(x1, ..., xn)`.
     *
@@ -76,7 +76,7 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     d should be(res3)
   }
 
-  /** Of course an extractor can be used in pattern matching...
+  /** An extractor can also be used in pattern matching:
     */
   def patternMatchingExtractors(res0: String, res1: String) {
     class Car(val make: String, val model: String, val year: Short, val topSpeed: Short)
@@ -94,7 +94,7 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     x._2 should be(res1)
   }
 
-  /** Since we aren't really using u and v in the previous pattern matching with can replace them with _.
+  /** Since we aren't really using `u` and `v` in the previous pattern matching, they can be replaced with `_`:
     */
   def withWildcardExtractors(res0: String, res1: String) {
     class Car(val make: String, val model: String, val year: Short, val topSpeed: Short)
@@ -132,7 +132,7 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     result should be(res0)
   }
 
-  /** An extractor can be any stable object, including instantiated classes with an unapply method.
+  /** An extractor can be any stable object, including instantiated classes with an unapply method:
     */
   def anyObjectExtractors(res0: String) {
     class Car(val make: String, val model: String, val year: Short, val topSpeed: Short) {
@@ -149,7 +149,7 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     result should be(res0)
   }
 
-  /** What is typical is to create a custom extractor in the companion object of the class. In this exercise, we use it as an assignment:
+  /** A custom extractor is typically created in the companion object of the class. In this exercise, we use it as an assignment:
     */
   def asAssignmentExtractors(res0: String, res1: Option[String], res2: String) {
     class Employee(
@@ -174,7 +174,7 @@ object Extractors extends FlatSpec with Matchers with org.scalaexercises.definit
     c should be(res2)
   }
 
-  /** In this exercise we use the unapply for pattern matching employee objects
+  /** In this exercise we use `unapply` for pattern matching employee objects:
     */
   def unapplyForPatternMatchingExtractors(res0: String) {
     class Employee(

src/main/scala/stdlib/ForExpressions.scala

@@ -7,7 +7,7 @@ import org.scalatest._
   */
 object ForExpressions extends FlatSpec with Matchers with org.scalaexercises.definitions.Section {
 
-  /** For expressions can nest, with later generators varying more rapidly than earlier ones:
+  /** `for` expressions can nest, with later generators varying more rapidly than earlier ones:
     */
   def canBeNestedForExpressions(res0: Int, res1: Int) {
     val xValues = 1 to 4
@@ -19,7 +19,7 @@ object ForExpressions extends FlatSpec with Matchers with org.scalaexercises.def
     coordinates(4) should be(res0, res1)
   }
 
-  /** Using `for` we can make more readable code
+  /** Using `for` we can make more readable code:
     */
   def readableCodeForExpressions(res0: List[Int]) {
     val nums = List(List(1), List(2), List(3), List(4), List(5))

src/main/scala/stdlib/HigherOrderFunctions.scala

@@ -9,7 +9,7 @@ object HigherOrderFunctions extends FlatSpec with Matchers with org.scalaexercis
 
   /** Meet lambda. Scala provides a relatively lightweight syntax for defining anonymous functions. Anonymous functions in source code are called function literals and at run time, function literals are instantiated into objects called function values.
     *
-    * Scala supports first-class functions, which means you can express functions in function literal syntax, i.e.,` (x: Int) => x + 1`, and those functions can be represented by objects, which are called function values.
+    * Scala supports first-class functions, which means you can express functions in function literal syntax, i.e. ` (x: Int) => x + 1`, and those functions can be represented by objects, which are called function values.
     */
   def meetLambdaHigherOrderFunctions(res0: Int, res1: Int, res2: Int, res3: Int, res4: Int, res5: Int) {
     def lambda = { x: Int ⇒ x + 1 }
@@ -38,7 +38,7 @@ object HigherOrderFunctions extends FlatSpec with Matchers with org.scalaexercis
     result5 should be(res5)
   }
 
-  /** An anonymous function can also take on a different look by taking out the brackets
+  /** An anonymous function can also take on a different look by taking out the brackets:
     */
   def differentLookHigherOrderFunctions(res0: Int) {
     def lambda = (x: Int) ⇒ x + 1
@@ -68,7 +68,7 @@ object HigherOrderFunctions extends FlatSpec with Matchers with org.scalaexercis
     result2 should be(res1)
   }
 
-  /** We can take that closure and throw it into a method and it will still hold the environment
+  /** We can take that closure and throw it into a method and it will still hold the environment:
     */
   def holdEnvironmentHigherOrderFunctions(res0: Int, res1: Int) {
     def summation(x: Int, y: Int ⇒ Int) = y(x)
@@ -123,7 +123,7 @@ object HigherOrderFunctions extends FlatSpec with Matchers with org.scalaexercis
 
   /** Function taking another function as a parameter. Helps in composing functions.
     *
-    * Hint: a map method applies the function to each element of a list
+    * Hint: a map method applies the function to each element of a list.
     */
   def functionAsParameterHigherOrderFunctions(res0: List[String], res1: List[String], res2: List[Int]) {
     def makeUpper(xs: List[String]) = xs map {

src/main/scala/stdlib/Implicits.scala

@@ -10,8 +10,8 @@ object Implicits extends FlatSpec with Matchers with org.scalaexercises.definiti
 
   /** The actual arguments that are eligible to be passed to an implicit parameter fall into two categories: 
     *
-    * - First, eligible are all identifiers x that can be accessed at the point of the method call without a prefix and that denote an implicit definition or an implicit parameter. 
-    * - Second, eligible are also all members of companion modules of the implicit parameter's type that are labeled implicit.
+    *  - First, eligible are all identifiers x that can be accessed at the point of the method call without a prefix and that denote an implicit definition or an implicit parameter. 
+    *  - Second, eligible are also all members of companion modules of the implicit parameter's type that are labeled implicit.
     *
     * In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values can not be top-level, they have to be members of a template.
     *
@@ -46,7 +46,7 @@ object Implicits extends FlatSpec with Matchers with org.scalaexercises.definiti
     * abc
     * }}}
     *
-    * Implicits wrap around existing classes to provide extra functionality. This is similar to *monkey patching* in **Ruby**, and *Meta-Programming* in **Groovy**.
+    * Implicits wrap around existing classes to provide extra functionality. This is similar to monkey patching in Ruby and meta-programming in Groovy.
     *
     * Creating a method `isOdd` for `Int`, which doesn't exist:
     */

src/main/scala/stdlib/InfixPrefixandPostfixOperators.scala

@@ -8,15 +8,15 @@ import scala.language.postfixOps
   */
 object InfixPrefixandPostfixOperators extends FlatSpec with Matchers with org.scalaexercises.definitions.Section {
 
-  /** Any method which takes a single parameter can be used as an infix operator: `a.m(b)` can be written `a m b`.
+  /** Any method which takes a single parameter can be used as an infix operator: `a.m(b)` can also be written as `a m b`.
     */
   def singleParameterInfixPrefixandPostfixOperators(res0: Int, res1: Int) {
     val g: Int = 3
     (g + 4) should be(res0) // + is an infix operator
     g.+(4) should be(res1) // same result but not using the infix operator
   }
 
-  /** Infix Operators do NOT work if an object has a method that takes two parameters:
+  /** Infix operators do NOT work if an object has a method that takes two parameters:
     */
   def notWithTwoInfixPrefixandPostfixOperators(res0: Int, res1: Int) {
     val g: String = "Check out the big brains on Brad!"
@@ -28,14 +28,14 @@ object InfixPrefixandPostfixOperators extends FlatSpec with Matchers with org.sc
     g.indexOf('o', 7) should be(res1) //indexOf(Char, Int) must use standard java/scala calls
   }
 
-  /** Any method which does not require a parameter can be used as a postfix operator: `a.m` can be written `a m`.
+  /** Any method which does not require a parameter can be used as a postfix operator: `a.m` can be written as `a m`.
     *
-    * For instance `a.##(b)` can be written `a ## b` and `a.!` can be written `a!`
+    * For instance, `a.+(b)` is equivalent to `a + b` and `a.!` is the same as `a!`.
     *
-    * **Postfix operators** have lower precedence than **infix operators**, so:
-    * - `foo bar baz` means `foo.bar(baz)`.
-    * - `foo bar baz bam` means `(foo.bar(baz)).bam`
-    * - `foo bar baz bam bim` means `(foo.bar(baz)).bam(bim)`.
+    * Postfix operators have lower precedence than infix operators, so:
+    *  - `foo bar baz` means `foo.bar(baz)`.
+    *  - `foo bar baz bam` means `(foo.bar(baz)).bam`
+    *  - `foo bar baz bam bim` means `(foo.bar(baz)).bam(bim)`.
     */
   def postfixOperatorInfixPrefixandPostfixOperators(res0: String) {
     val g: Int = 31
@@ -50,7 +50,7 @@ object InfixPrefixandPostfixOperators extends FlatSpec with Matchers with org.sc
     (-g) should be(res0)
   }
 
-  /** Here we create our own prefix operator for our own class. The only identifiers that can be used as prefix operators are `+`, `-`, `!`, and `~`:
+  /** Here's how to create a prefix operator for our own class. The only identifiers that can be used as prefix operators are `+`, `-`, `!`, and `~`:
     */
   def ourOwnOperatorInfixPrefixandPostfixOperators(res0: String, res1: String) {
     class Stereo {