Tweak the text.

Author: som-snytt

_tour/singleton-objects.md

@@ -13,11 +13,13 @@ previous-page: pattern-matching
 redirect_from: "/tutorials/tour/singleton-objects.html"
 prerequisite-knowledge: classes, methods, private-methods, packages, option
 ---
+An object is a class that has exactly one instance. It is created lazily when it is referenced, like a lazy val.
 
-A singleton object is an instance of a new class. There is exactly one instance of each singleton object. They do not have constructors so they cannot be instantiated.
+As a top-level value, an object is a singleton.
 
+As a member of an enclosing class or as a local value, it behaves exactly like a lazy val.
 # Defining a singleton object
-The simplest form of an object is the keyword `object` and an identifier:
+An object is a value. The definition of an object looks like a class, but uses the keyword `object`:
 ```tut
 object Box
 ```
@@ -30,42 +32,49 @@ object Logger {
   def info(message: String): Unit = println(s"INFO: $message")
 }
 ```
-The method `info` can be imported from anywhere in the program. Creating utility methods like this is a common use case for singleton objects (however, more sophisticated logging techniques exist). Let's see how to use `info` in another package:
+The method `info` can be imported from anywhere in the program. Creating utility methods like this is a common use case for singleton objects.
+
+Let's see how to use `info` in another package:
 
 ```
 import logging.Logger.info
 
 class Project(name: String, daysToComplete: Int)
 
-val project1 = new Project("TPS Reports", 1)
-val project2 = new Project("Website redesign", 5)
-info("Created projects")  // Prints "INFO: Created projects"
+class Test {
+  val project1 = new Project("TPS Reports", 1)
+  val project2 = new Project("Website redesign", 5)
+  info("Created projects")  // Prints "INFO: Created projects"
+}
 ```
 
-The `info` method becomes visible in the scope of the package using `import logging.Logger.info`. You could also use `import logging.Logger._` to import everything from Logger.
+The `info` method is visible because of the import statement, `import logging.Logger.info`.
 
-Note: If an `object` is nested within another construct such as a class, it is only a singleton in that context. This means there could be an `object NutritionInfo` in the `class Milk` and in the `class OrangeJuice`.
+Imports require a "stable path" to the imported symbol, and an object is a stable path.
+
+Note: If an `object` is not top-level but is nested in another class or object, then the object is "path-dependent" like any other member. This means that given two kinds of beverages, `class Milk` and `class OrangeJuice`, a class member `object NutritionInfo` "depends" on the enclosing instance, either milk or orange juice. `milk.NutritionInfo` is entirely distinct from `oj.NutritionInfo`.
 
 ## Companion objects
 
-A singleton object with the same name as a class is called a _companion object_. Conversely, the class is the object's companion class. The companion class and object can access each other's private members. Use a companion object for methods and values which are not specific to instances of the companion class.
+An object with the same name as a class is called a _companion object_. Conversely, the class is the object's companion class. A companion class or object can access the private members of its companion. Use a companion object for methods and values which are not specific to instances of the companion class.
 ```
 import scala.math._
 
-class Circle(val radius: Double) {
-  def area: Double = Circle.calculateArea(radius)
+case class Circle(radius: Double) {
+  import Circle._
+  def area: Double = calculateArea(radius)
 }
 
 object Circle {
-  def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0)
+  private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0)
 }
 
 val circle1 = new Circle(5.0)
 
 circle1.area
 ```
 
-The `class Circle` contains the val `radius` which is specific to each instance whereas the `object Circle` contains the method `calculateArea` which is the same for every instance.
+The `class Circle` has a member `area` which is specific to each instance, and the singleton `object Circle` has a method `calculateArea` which is available to every instance.
 
 The companion object can also contain factory methods:
 ```tut
@@ -92,9 +101,10 @@ scalaCenterEmail match {
 ```
 The `object Email` contains a factory `fromString` which creates an `Email` instance from a String. We return it as an `Option[Email]` in case of parsing errors.
 
-Note: If a class or object has a companion, both must be defined in the same file. To define them in the REPL, you must enter `:paste` and then paste in the class and companion object code.
+Note: If a class or object has a companion, both must be defined in the same file. To define companions in the REPL, either define them on the same line or enter `:paste` mode.
 
 ## Notes for Java programmers ##
 
-`static` is not a keyword in Scala. Instead, all members that would be static, including classes, should go in a singleton object instead.
+`static` members in Java are modeled as ordinary members of a companion object in Scala.
+
 When using a companion object from Java code, the members will be defined in a companion class with a `static` modifier. This is called _static forwarding_. It occurs even if you haven't defined a companion class yourself.