Tweak up per review

Author: som-snytt

library/src/scala/util/Using.scala

@@ -47,20 +47,21 @@ import scala.util.control.{ControlThrowable, NonFatal}
   * val files = List("file1.txt", "file2.txt", "file3.txt", "file4.txt")
   * val lines: Try[Seq[String]] = Using.Manager { use =>
   *   // acquire resources
-  *   def reader(filename: String) = use(new BufferedReader(new FileReader(filename)))
+  *   def mkreader(filename: String) = use(new BufferedReader(new FileReader(filename)))
   *
   *   // use your resources here
   *   def lines(reader: BufferedReader): Iterator[String] =
   *     Iterator.continually(reader.readLine()).takeWhile(_ != null)
   *
-  *   files.map(reader).flatMap(lines)
+  *   files.map(mkreader).flatMap(lines)
   * }
   * }}}
   *
   * Composed or "wrapped" resources may be acquired in order of construction,
-  * if "underlying" resources are not closed:
+  * if "underlying" resources are not closed. Although redundant in this case,
+  * here is the previous example with a wrapped call to `use`:
   * {{{
-  *   def reader(filename: String) = use(new BufferedReader(use(new FileReader(filename))))
+  *   def mkreader(filename: String) = use(new BufferedReader(use(new FileReader(filename))))
   * }}}
   *
   * Custom resources can be registered on construction by requiring an implicit `Manager`.
@@ -76,7 +77,7 @@ import scala.util.control.{ControlThrowable, NonFatal}
   *   val xres = X(x)
   *   override def close() = println(s"CLOSE $y")
   *   // an error during construction releases previously acquired resources
-  *   assert(y != null, "y is null")
+  *   require(y != null, "y is null")
   *   mgr.acquire(this)
   * }
   *
@@ -88,7 +89,7 @@ import scala.util.control.{ControlThrowable, NonFatal}
   *   Using.Manager { implicit mgr =>
   *     Y(null)("X")
   *   }
-  * } // Failure(java.lang.AssertionError: assertion failed: y is null)
+  * } // Failure(java.lang.IllegalArgumentException: requirement failed: y is null)
   * }}}
   *
   * If you wish to avoid wrapping management and operations in a `Try`, you can use