Documentation patches, tweaks and completion

README.md

@@ -40,6 +40,6 @@ Here is an example : `1.5.7-3-g2aabbbf.dirty`
 ## How to release (and have a nice version number)
 
 1. `git commit`
-1. `git tag -a MAJOR.MINOR.SUB -m "tag vMAJOR.MINOR.SUB"`
-1. `git push origin MAJOR.MINOR.SUB`
-2. This commits everyhing and tags it adequately. When this has been done, you can then draft a new release and upload the corresponding `jar` file from above in Github releases. Creating a tag triggers the documentation update. Voilà, you're all set.
+2. `git tag -a MAJOR.MINOR.SUB -m "tag vMAJOR.MINOR.SUB"`
+3. `git push origin MAJOR.MINOR.SUB`
+4. This commits everyhing and tags it adequately. When this has been done, you can then draft a new release and upload the corresponding `jar` file from above in GitHub releases. Creating a tag triggers the documentation update. Voilà, you're all set.

src/main/scala/hevs/graphics/AcceleratedDisplay.scala

@@ -1,21 +1,10 @@
 package hevs.graphics
 
 import hevs.graphics.utils.GraphicTimer
-import java.awt.Color
-import java.awt.Dimension
-import java.awt.DisplayMode
-import java.awt.Graphics2D
-import java.awt.GraphicsConfiguration
-import java.awt.GraphicsDevice
-import java.awt.GraphicsEnvironment
-import java.awt.RenderingHints
-import java.awt.Toolkit
-import java.awt.Transparency
-import java.awt.image.BufferStrategy
-import java.awt.image.BufferedImage
-import javax.swing.JFrame
-import javax.swing.SwingWorker
-import javax.swing.UIManager
+
+import java.awt._
+import java.awt.image.{BufferStrategy, BufferedImage}
+import javax.swing.{JFrame, SwingWorker, UIManager}
 
 
 object AcceleratedDisplay {
@@ -77,11 +66,11 @@ abstract class AcceleratedDisplay {
   }
 
   /**
-   * @see #AcceleratedDisplay(int, int, int, int, String, boolean)
-   * @param width
-   * @param height
-   * @param title
-   * @param high_quality
+   * @see AcceleratedDisplay(Int, Int, Int, Int, String, Boolean)
+   * @param width the width of the window (in pixels)
+   * @param height the height of the window (in pixels)
+   * @param title the title of the window
+   * @param high_quality whether to enable antialiasing or not
    */
   def this(width: Int, height: Int, title: String, high_quality: Boolean) =  {
     this()
@@ -91,14 +80,14 @@ abstract class AcceleratedDisplay {
 
   /**
    *
-   * @param width
-   * @param height
-   * @param xPos x offset position of the window on the screen, -1 for
+   * @param width the width of the window (in pixels)
+   * @param height the height of the window (in pixels)
+   * @param xPos the x offset position of the window on the screen, -1 for
    *             centered
-   * @param yPos y offset position of the window on the screen, -1 for
+   * @param yPos the y offset position of the window on the screen, -1 for
    *             centered
-   * @param title
-   * @param high_quality
+   * @param title the title of the window
+   * @param high_quality whether to enable antialiasing or not
    */
   def this(width: Int, height: Int, xPos: Int, yPos: Int, title: String, high_quality: Boolean) = {
     this()
@@ -107,11 +96,11 @@ abstract class AcceleratedDisplay {
   }
 
   /**
-   * @param title
-   * @param width
-   * @param height
-   * @param xOffset The x offset of the window on the screen, -1 if centered
-   * @param yOffset The y offset of the window on the screen, -1 if centered
+   * @param title the title of the window
+   * @param width the width of the window (in pixels)
+   * @param height the height of the window (in pixels)
+   * @param xOffset the x offset of the window on the screen, -1 if centered
+   * @param yOffset the y offset of the window on the screen, -1 if centered
    */
   private def initFrame(title: String, width: Int, height: Int, xOffset: Int, yOffset: Int): Unit = { // Shall we try a different look for the window ?
     try UIManager.setLookAndFeel("javax.swing.plaf.nimbus.NimbusLookAndFeel")
@@ -244,7 +233,7 @@ abstract class AcceleratedDisplay {
   /**
    * Call this method periodically to have a constant frame rate
    *
-   * @param FPS
+   * @param FPS the target frame rate
    */
   def syncGameLogic(FPS: Int): Unit = {
     gt.sync(FPS)

src/main/scala/hevs/graphics/FunGraphics.scala

@@ -1,20 +1,18 @@
 package hevs.graphics
 
-import hevs.graphics.interfaces.DualLayerGraphics
-import hevs.graphics.interfaces.Graphics
-import hevs.graphics.utils.GraphicsBitmap
-import hevs.graphics.utils.RepeatingReleasedEventsFixer
+import hevs.graphics.interfaces.{DualLayerGraphics, Graphics}
+import hevs.graphics.utils.{GraphicsBitmap, RepeatingReleasedEventsFixer}
 
-import javax.imageio.ImageIO
 import java.awt._
 import java.awt.event._
-import java.awt.font.{LineMetrics, TextLayout}
+import java.awt.font.LineMetrics
 import java.awt.geom.{AffineTransform, Rectangle2D}
 import java.io._
+import javax.imageio.ImageIO
 import javax.swing.SwingConstants
 
 /**
- * Factory for [[hevs.graphics.FunGraphics]].
+ * Factory for [[FunGraphics]].
  */
 object FunGraphics {
   var major = 0
@@ -275,8 +273,8 @@ class FunGraphics(val width: Int, val height: Int, val xoffset: Int, val yoffset
     g2d.drawOval(posX, posY, f, f)
   }
 
-  override def drawFilledCircle(posX: Int, posY: Int, radius: Int): Unit = {
-    g2d.fillOval(posX, posY, radius, radius)
+  override def drawFilledCircle(posX: Int, posY: Int, diameter: Int): Unit = {
+    g2d.fillOval(posX, posY, diameter, diameter)
   }
 
   override def drawFilledOval(posX: Int, posY: Int, width: Int, height: Int): Unit = {
@@ -455,13 +453,14 @@ class FunGraphics(val width: Int, val height: Int, val xoffset: Int, val yoffset
 
   override def getAvailableFonts(): Array[String] = GraphicsEnvironment.getLocalGraphicsEnvironment.getAvailableFontFamilyNames
 
-  /**
-   * A sample game loop using explicit synchronization (if display flickers)
-   */
+
   private[graphics] var pressedUp = false
   private[graphics] var pressedDown = false
   private[graphics] var size = 1
 
+  /**
+   * A sample game loop using explicit synchronization (if display flickers)
+   */
   private[graphics] def gameloopSample(): Unit = {
     var i = 1
     var direction = 1

src/main/scala/hevs/graphics/ImageGraphics.scala

@@ -1,15 +1,12 @@
 package hevs.graphics
 
-import java.awt.Color
-import java.awt.Graphics
-import java.awt.Toolkit
 import java.awt.image.BufferedImage
+import java.awt.{Color, Graphics, Toolkit}
 import javax.imageio.ImageIO
 import javax.swing.JFrame
 
-
 /**
- * [ImageGraphics] helpers.
+ * [[ImageGraphics]] helpers.
  */
 @SerialVersionUID(6832022057915586803L)
 object ImageGraphics {
@@ -35,6 +32,11 @@ object ImageGraphics {
     values
   }
 
+  /**
+   * Converts a color array to a black-or-white array as Int values
+   * @param c The color array
+   * @return The array converted to BW
+   */
   def convertToGrayInt(c: Array[Array[Color]]): Array[Array[Int]] = {
     val w = c.length
     val h = c(0).length
@@ -49,6 +51,10 @@ object ImageGraphics {
     values
   }
 
+  /**
+   * Test of the class
+   * @param args unused
+   */
   def main(args: Array[String]): Unit = {
     val imageUsed = "/images/lena.bmp"
     val org = new ImageGraphics(imageUsed, "Original", 0, 0)
@@ -57,15 +63,15 @@ object ImageGraphics {
 
 /**
  * This class was made to deal with images as multidimensional arrays.
- * Mainly used in the <code>ImageProcessing</code> lab. It expects the images to reside in the <code>src</code> directory
+ * Mainly used in the `ImageProcessing` lab. It expects the images to reside in the `src` directory
  *
  * @author Pierre-André Mudry
  * @version 1.0
  * @constructor
  * @param backGroundFilePath the path of the file
  * @param windowTitle the title
  * @param xPositionOffset the x offset
- * @param yPositionOffset the y offet
+ * @param yPositionOffset the y offset
  */
 @SerialVersionUID(6832022057915586803L)
 class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val xPositionOffset: Int, val yPositionOffset: Int) extends JFrame {
@@ -110,9 +116,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
    * is slow. If required, please call [[java.awt.Component#repaint()]] if needed after
    * you have updated all the pixels you need.
    *
-   * @param x
-   * @param y
-   * @param intensity
+   * @param x X position of the pixel
+   * @param y Y position of the pixel
+   * @param intensity grayscale value of the pixel
    */
   def setPixelBW(x: Int, y: Int, intensity: Int): Unit = {
     if (!((x < 0) || (y < 0) || (x >= w) || (y >= h))) backgroundBitmap.setRGB(x, y, intensity << 16 | intensity << 8 | intensity)
@@ -121,7 +127,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
   /**
    * Sets an array of grayscale pixels (from 0 to 255) and displays them
    *
-   * @param pixels
+   * @param pixels the 2D array of grayscale pixels
    */
   def setPixelsBW(pixels: Array[Array[Int]]): Unit = {
     try {
@@ -140,9 +146,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
   }
 
   /**
-   * Sets an array of pixels of Color and displays them
+   * Sets an array of pixels of [[Color]] and displays them
    *
-   * @param pixels
+   * @param pixels the 2D of [[Color]] pixels
    */
   def setPixelsColor(pixels: Array[Array[Color]]): Unit = {
     try {
@@ -165,7 +171,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
    *
    * @param x the x coordinate
    * @param y the y coordinate
-   * @return the pixel
+   * @return the pixel's grayscale value
    */
   def getPixelBW(x: Int, y: Int): Int = if ((x < 0) || (y < 0) || (x >= w) || (y >= h)) 0
   else { // Inside the image. Make the gray conversion and return the value
@@ -177,7 +183,7 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
    * Gets the array of the pixels (which have been converted to grayscale
    * if required)
    *
-   * @return The arrays of gray pixels
+   * @return the 2D array of grayscale pixels
    */
   def getPixelsBW(): Array[Array[Int]] = {
     val values = Array.ofDim[Int](w, h)
@@ -191,9 +197,9 @@ class ImageGraphics(val backGroundFilePath: String, val windowTitle: String, val
   }
 
   /**
-   * Gets the array of the pixels as Colors (see #Color)
+   * Gets the array of the pixels as [[Color]]s
    *
-   * @return The arrays of pixels
+   * @return the 2D array of [[Color]] pixels
    */
   def getPixelsColor(): Array[Array[Color]] = {
     val values = Array.ofDim[Color](w, h)

src/main/scala/hevs/graphics/TurtleGraphics.scala

@@ -1,17 +1,14 @@
 package hevs.graphics
 
-import java.awt.BasicStroke
-import java.awt.Color
-import java.awt.Point
+import java.awt.{BasicStroke, Color, Point}
 import java.awt.event.MouseMotionListener
 
-
 /**
  * Graphics class that emulates the tortoise in the Logo programming language
  *
  * The turtle starts at the center of the window, looking up with a black color and pen down
  *
- * Basic port implementation by Pierre Roduit, rewritten for use with {@link FunGraphics}
+ * Basic port implementation by Pierre Roduit, rewritten for use with [[FunGraphics]]
  * by Pierre-André Mudry.
  *
  * @see <a href="http://en.wikipedia.org/wiki/Turtle_graphics">Wikipedia
@@ -41,6 +38,11 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra
     this(width, height, null)
   }
 
+  /**
+   * Rounds a Double value and converts it to Int
+   * @param a the value to round
+   * @return the rounded value
+   */
   private def round(a: Double) = a.round.toInt
 
   /**
@@ -55,7 +57,7 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra
   /**
    * Change the color of drawing
    *
-   * @param color
+   * @param color the new color
    */
   def changeColor(color: Color): Unit = {
     setColor(color)
@@ -99,27 +101,29 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra
   }
 
   /**
+   * Gets the turtle's current position
    * @return The location of the turtle
    */
-  def getPosition() = new Point(round(x), round(y))
+  def getPosition(): Point = new Point(round(x), round(y))
 
   /**
    * Sets the width of the pen
    *
-   * @param w
+   * @param w the new width
    */
   def setWidth(w: Float): Unit = {
     g2d.setStroke(new BasicStroke(w))
   }
 
   /**
+   * Gets the turtle's current angle
    * @return The current turtle angle (in degrees)
    *         Angle 0 is east (right). A positive angle is clockwise.
    */
   def getTurtleAngle(): Double = this.angle * 180.0 / Math.PI
 
   /**
-   * Turn the direction of writing with the specified angle
+   * Turn the direction of writing with by specified angle
    * A positive angle is clockwise.
    *
    * @param angle specified angle in degrees
@@ -140,7 +144,7 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra
   }
 
   /**
-   * Turn the direction of writing with the specified angle.
+   * Turn the direction of writing by the specified angle.
    * A positive angle is clockwise.
    *
    * @param angle
@@ -169,6 +173,10 @@ class TurtleGraphics(width: Int, height: Int, windowName: String) extends FunGra
    */
   def getTurtleAngleRad(): Double = this.angle
 
+  /**
+   * Adds a [[MouseMotionListener]] to the window to react on mouse movements
+   * @param mouseMotionListener the [[MouseMotionListener]]
+   */
   def setMouseMotionManager(mouseMotionListener: MouseMotionListener): Unit = {
     this.mainFrame.addMouseMotionListener(mouseMotionListener)
   }