improve documentation, minor refactoring and fixes

Author: bjornregnell

src/main/scala/introprog/Dialog.scala

@@ -1,5 +1,6 @@
 package introprog
 
+/** A module with utilities for creating standard GUI dialogs. */
 object Dialog {
   import javax.swing.{JFileChooser, JOptionPane, JColorChooser}
 

src/main/scala/introprog/IO.scala

@@ -1,6 +1,8 @@
 package introprog
 
+/** A model with input/output operations from/to the underlying file system. */
 object IO {
+  /** Load a string from a text file called `fileName` using encoding `enc`. */
   def loadString(fileName: String, enc: String = "UTF-8"): String = {
     //This implementation risk leak open file handles:
     //   scala.io.Source.fromFile(fileName, enc).mkString
@@ -11,6 +13,7 @@ object IO {
     result
   }
 
+  /** Load string lines from a text file called `fileName` using encoding `enc`. */
   def loadLines(fileName: String, enc: String = "UTF-8"): Vector[String] = {
     //This implementation risk leak open file handles:
     //   scala.io.Source.fromFile(fileName, enc).getLines.toVector
@@ -21,39 +24,49 @@ object IO {
     result
   }
 
-  def saveString(s: String, fileName: String, enc: String = "UTF-8"): Unit = {
+  /** Save `text` to a text file called `fileName` using encoding `enc`. */
+  def saveString(text: String, fileName: String, enc: String = "UTF-8"): Unit = {
     val f = new java.io.File(fileName)
     val pw = new java.io.PrintWriter(f, enc)
-    try pw.write(s) finally pw.close()
+    try pw.write(text) finally pw.close()
   }
 
+  /** Save `lines` to a text file called `fileName` using encoding `enc`. */
   def saveLines(lines: Seq[String], fileName: String, enc: String = "UTF-8"): Unit =
     saveString(lines.mkString("\n"), fileName, enc)
 
+  /** Load a serialized object from a binary file called `fileName`. */
   def loadObject[T](fileName: String): T = {
     val f = new java.io.File(fileName)
     val ois = new java.io.ObjectInputStream(new java.io.FileInputStream(f))
     try { ois.readObject.asInstanceOf[T] } finally ois.close()
   }
 
+  /** Serialize `obj` to a binary file called `fileName`. */
   def saveObject[T](obj: T, fileName: String): Unit = {
     val f = new java.io.File(fileName)
     val oos = new java.io.ObjectOutputStream(new java.io.FileOutputStream(f))
     try oos.writeObject(obj) finally oos.close()
   }
 
+  /** Test if a file with name `fileName` exists. */
   def isExisting(fileName: String): Boolean = new java.io.File(fileName).exists
 
+  /** Create a directory with name ´dir´ if it does not exist. */
   def createDirIfNotExist(dir: String): Boolean = new java.io.File(dir).mkdirs()
 
+  /** Return the path name or the current user's home directory. */
   def userDir: String = System.getProperty("user.home")
 
+  /** Return the path name or the current working directory. */
   def currentDir: String =
     java.nio.file.Paths.get(".").toAbsolutePath.normalize.toString
 
+  /** Return a sequence of file names in the directory `dir`. */
   def list(dir: String = "."): Vector[String] =
     Option(new java.io.File(dir).list).map(_.toVector).getOrElse(Vector())
 
+  /** Change name of file `from`, DANGER: silently replaces existing `to`. */
   def move(from: String, to: String): Unit = {
     import java.nio.file.{Files, Paths, StandardCopyOption}
     Files.move(Paths.get(from), Paths.get(to), StandardCopyOption.REPLACE_EXISTING)

src/main/scala/introprog/PixelWindow.scala

@@ -1,14 +1,14 @@
 package introprog
 
-/** A window for pixel-based drawing in an underlying Swing window. */
+/** A module with utilities for event handling in `PixelWindow` instances. */
 object PixelWindow {
   /** Immediately exit running application, close all windows, kills all threads. */
   def exit(): Unit = System.exit(0)
 
   /** Idle waiting for `millis` milliseconds. */
   def delay(millis: Long): Unit = Thread.sleep(millis)
 
-  /** An object with strings describing events that can happen in a PixelWindow, see [[introprog.PixelWindow.Event]] */
+  /** An object with integers representing events that can happen in a PixelWindow. */
   object Event {
     /** An integer representing a key down event.
     *
@@ -57,7 +57,7 @@ object PixelWindow {
       */
     val Undefined     = 0
 
-    /** Returns a descriptive string with name of the `event` number */
+    /** Returns a descriptive text for each `event`. */
     def show(event: Int): String = event match {
       case KeyPressed    => "KeyPressed"
       case KeyReleased   => "KeyReleased"
@@ -71,14 +71,14 @@ object PixelWindow {
   }
 }
 
-/** A window with a canvas for pixel-based drawing implemented using Swing.
+/** A window with a canvas for pixel-based drawing.
   *
   * @constructor Create a new window for pixel-based drawing.
-  * @param width the number of horizontal pixels of the drawing canvas inside the window
-  * @param height number of vertical pixels of the drawing canvas inside the window
+  * @param width the number of horizontal pixels
+  * @param height number of vertical pixels
   * @param title the title of the window
-  * @param background the background color filling the canvas when clearing pixels
-  * @param foreground the foreground color used as default argument for color parameters
+  * @param background the color used when clearing pixels
+  * @param foreground the foreground color, default color in drawing operations
   */
 class PixelWindow(
   val width: Int = 800,
@@ -165,7 +165,7 @@ class PixelWindow(
     *
     * If time is out, `lastEventType` is `Undefined`.
     */
-  def awaitEvent(timeoutInMillis: Long): Unit = {
+  def awaitEvent(timeoutInMillis: Long = 1): Unit = {
     val e = eventQueue.poll(timeoutInMillis, java.util.concurrent.TimeUnit.MILLISECONDS)
     if (e != null) handleEvent(e) else _lastEventType = Event.Undefined
   }
@@ -180,7 +180,7 @@ class PixelWindow(
       g.drawLine(x1, y1, x2, y2)
     }
 
-  /** Fill a rectangle with upper left corner at `(x, y)` using `color` */
+  /** Fill a rectangle with upper left corner at `(x, y)` using `color`. */
   def fill(x: Int, y: Int, width: Int, height: Int, color: java.awt.Color = foreground): Unit =
     canvas.withGraphics { g =>
       g.setColor(color)
@@ -205,10 +205,10 @@ class PixelWindow(
   }
 
   /** Show the window. Has no effect if the window is already visible. */
-  def open(): Unit = Swing { frame.setVisible(true) }
+  def show(): Unit = Swing { frame.setVisible(true) }
 
   /** Hide the window. Has no effect if the window is already hidden. */
-  def close(): Unit = Swing { frame.setVisible(false); frame.dispose() }
+  def hide(): Unit = Swing { frame.setVisible(false); frame.dispose() }
 
   /** Clear all pixels using the `background` class parameter. */
   def clear(): Unit = canvas.withGraphics { g =>

src/main/scala/introprog/Swing.scala

@@ -1,14 +1,15 @@
 package introprog
 
-/** A module with Swing utilities. */
+/** A module with Swing utilities used by [[introprog.PixelWindow]]. */
 object Swing {
 
   private def runInSwingThread(callback: => Unit): Unit =
     javax.swing.SwingUtilities.invokeLater(() => callback)
 
-  /** Run `callback` in Swing thread using `javax.swing.SwingUtilities.invokeLater`. */
+  /** Run `callback` asynchronously in the Swing thread. */
   def apply(callback: => Unit): Unit = runInSwingThread(callback)
 
+  /** Run `callback` in the Swing thread and block until completion. */
   def await[T: scala.reflect.ClassTag](callback: => T): T = {
     val ready = new java.util.concurrent.CountDownLatch(1)
     val result = new Array[T](1)
@@ -20,24 +21,27 @@ object Swing {
     result(0)
   }
 
+  /** Return a sequence of available look and feel options. */
   def installedLookAndFeels: Vector[String] =
     javax.swing.UIManager.getInstalledLookAndFeels.toVector.map(_.getClassName)
 
+  /** Find a look and feel with a name including `partOfName`. */
   def findLookAndFeel(partOfName: String): Option[String] =
     installedLookAndFeels.find(_.toLowerCase contains partOfName)
 
+  /** Test if the current operating system name includes `partOfName`. */
   def isOS(partOfName: String): Boolean =
     scala.sys.props("os.name").toLowerCase.contains(partOfName.toLowerCase)
 
-  var isInit = false
+  private var isInit = false
 
   /** Init the Swing GUI toolkit and set platform-specific look and feel.*/
   def init(): Unit = if (!isInit) {
     setPlatformSpecificLookAndFeel()
     isInit = true
   }
 
-  def setPlatformSpecificLookAndFeel(): Unit = {
+  private def setPlatformSpecificLookAndFeel(): Unit = {
     import javax.swing.UIManager.setLookAndFeel
     if (isOS("linux")) findLookAndFeel("gtk").foreach(setLookAndFeel)
     else if (isOS("win")) findLookAndFeel("win").foreach(setLookAndFeel)
@@ -72,11 +76,13 @@ object Swing {
       true
   	}
 
+    /** Execute `action` in the Swing thread with graphics context as param. */
     def withGraphics(action: java.awt.Graphics2D => Unit) = runInSwingThread {
       action(img.createGraphics())
       repaint()
     }
 
+    /** Execute `action` in the Swing thread with raw image as param. */
     def withImage(action: java.awt.image.BufferedImage => Unit) = runInSwingThread {
       action(img)
       repaint()