From 08043043a73688559aa1a79c90edae0ee63b36f3 Mon Sep 17 00:00:00 2001
From: hama <hama@siduction.net>
Date: Thu, 9 Oct 2014 23:48:51 +0200
Subject: [PATCH] documentation (javadoc)

---
 .gitignore                               |  1 +
 src/jlecture/simulation/DimensionRW.java |  2 ++
 src/jlecture/simulation/ISheet.java      |  6 ++++
 src/jlecture/simulation/IWidget.java     |  2 +-
 src/jlecture/simulation/Model.java       | 19 ++++++++++-
 src/jlecture/simulation/PointRW.java     |  5 +++
 src/jlecture/simulation/RectangleRW.java |  4 +++
 src/jlecture/simulation/Robot.java       | 14 +++++++-
 src/jlecture/simulation/Simulator.java   | 13 +++++++-
 src/jlecture/swt/PanelSWT.java           |  6 ++--
 src/jlecture/swt/RectangleSWT.java       | 24 ++++++++------
 src/jlecture/swt/SheetSWT.java           | 42 ++++++++++++++----------
 src/jlecture/swt/Widget.java             | 22 +++++++------
 src/jlecture/swt/XCross.java             | 24 +++++++-------
 14 files changed, 128 insertions(+), 56 deletions(-)

diff --git a/.gitignore b/.gitignore
index 8308dba..6e3b16e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 bin/
 .settings/
 
+doc/
diff --git a/src/jlecture/simulation/DimensionRW.java b/src/jlecture/simulation/DimensionRW.java
index 64afe20..eee8b88 100644
--- a/src/jlecture/simulation/DimensionRW.java
+++ b/src/jlecture/simulation/DimensionRW.java
@@ -29,7 +29,9 @@ public class DimensionRW extends Dimension {
      * Constructor
      *
      * @param width
+     *            horizontal dimension
      * @param height
+     *            vertical dimension
      */
     public DimensionRW(double width, double height) {
         this.width = width;
diff --git a/src/jlecture/simulation/ISheet.java b/src/jlecture/simulation/ISheet.java
index 77f43ff..335e896 100644
--- a/src/jlecture/simulation/ISheet.java
+++ b/src/jlecture/simulation/ISheet.java
@@ -1,5 +1,11 @@
 package jlecture.simulation;
 
+/**
+ * Defines a drawing area.
+ *
+ * @author hm
+ *
+ */
 public interface ISheet {
 
     /**
diff --git a/src/jlecture/simulation/IWidget.java b/src/jlecture/simulation/IWidget.java
index f8cb547..0a8bc7b 100644
--- a/src/jlecture/simulation/IWidget.java
+++ b/src/jlecture/simulation/IWidget.java
@@ -10,7 +10,7 @@ public interface IWidget {
     /**
      * Returns the center of the widget.
      *
-     * @return
+     * @return the center of the widget
      */
     public PointRW getCenter();
 
diff --git a/src/jlecture/simulation/Model.java b/src/jlecture/simulation/Model.java
index 3e56856..d16017a 100644
--- a/src/jlecture/simulation/Model.java
+++ b/src/jlecture/simulation/Model.java
@@ -11,6 +11,17 @@ import java.util.Random;
 /**
  * Implements the model of the simulator.
  *
+ * The model contains robots and bars in an area with real world coordinates.
+ * Another component is a drawing area to visualize the robots and bars.
+ *
+ * The model "know" the (modelled) real world, e.g. the position of the bars and
+ * robots.
+ *
+ * The model executes the simulation: the method onTimer() will be called
+ * periodically and does the simulator steps, e.g. it calculates the new
+ * position of the robots.
+ *
+ *
  * @author hm
  *
  */
@@ -31,6 +42,9 @@ public class Model {
 
     /**
      * Builds the elements of the simulator.
+     *
+     * Sets the bars and randomly the position of some robots with randomly set
+     * initial states (velocity, destination).
      */
     public void createModel() {
         things.add(new Bar(sheet.createRectangle(
@@ -119,7 +133,10 @@ public class Model {
     }
 
     /**
-     * Will be called every 100 millisec.
+     * Executes one simulator step.
+     *
+     * Will be called every 100 milliseconds and calculates the changes which
+     * are necessary for one simulation step.
      */
     public void onTimer() {
         if (isReady)
diff --git a/src/jlecture/simulation/PointRW.java b/src/jlecture/simulation/PointRW.java
index 6a6cb4f..7289d22 100644
--- a/src/jlecture/simulation/PointRW.java
+++ b/src/jlecture/simulation/PointRW.java
@@ -6,6 +6,9 @@ package jlecture.simulation;
 /**
  * Implements a position definition (x and y) with real world coordinates.
  *
+ * The real world coordinate system is like mathematical coordinate systems: the
+ * maximum x is right, the maximum y is at the top.
+ *
  * @author hm
  *
  */
@@ -23,7 +26,9 @@ public class PointRW {
      * Constructor.
      *
      * @param x
+     *            the x coordinate (horizontal)
      * @param y
+     *            the y coordinate (vertical)
      */
     public PointRW(double x, double y) {
         this.x = x;
diff --git a/src/jlecture/simulation/RectangleRW.java b/src/jlecture/simulation/RectangleRW.java
index e499024..cb2434a 100644
--- a/src/jlecture/simulation/RectangleRW.java
+++ b/src/jlecture/simulation/RectangleRW.java
@@ -32,9 +32,13 @@ public class RectangleRW {
      * Constructor.
      *
      * @param x
+     *            the x coordinate (horizontal) of the left lower corner
      * @param y
+     *            the y coordinate (vertical) of the left lower corner
      * @param width
+     *            the horizontal dimension of the rectangle
      * @param height
+     *            the vertical dimension of the rectangle
      */
     public RectangleRW(double x, double y, double width, double height) {
         this.x = x;
diff --git a/src/jlecture/simulation/Robot.java b/src/jlecture/simulation/Robot.java
index 0a7bae0..00deab3 100644
--- a/src/jlecture/simulation/Robot.java
+++ b/src/jlecture/simulation/Robot.java
@@ -4,6 +4,13 @@
 package jlecture.simulation;
 
 /**
+ * Implements a robot.
+ *
+ * A robot is a thing which can move. The move is defined by a start position, a
+ * destination position and a velocity.
+ *
+ * Using this data the simulator can calculate the current position.
+ *
  * @author hm
  *
  */
@@ -75,7 +82,7 @@ public class Robot extends ThingRW {
     }
 
     /**
-     * @return the widget
+     * @return the widget of the robot
      */
     public IWidget getWidget() {
         return widget;
@@ -84,8 +91,13 @@ public class Robot extends ThingRW {
     /**
      * Sets the current move.
      *
+     * The start position is the current position (the center of the widget).
+     *
      * @param destination
+     *            the destination of the move
      * @param velocity
+     *            the velocity in units per second. A unit is defined by the
+     *            real world coordinates
      */
     public void setMove(PointRW destination, double velocity) {
         start = widget.getCenter();
diff --git a/src/jlecture/simulation/Simulator.java b/src/jlecture/simulation/Simulator.java
index 5fcde3f..62788e0 100644
--- a/src/jlecture/simulation/Simulator.java
+++ b/src/jlecture/simulation/Simulator.java
@@ -11,17 +11,28 @@ import javax.swing.SwingUtilities;
 import jlecture.swt.SheetSWT;
 
 /**
+ * Defines the main routine of the simulator.
+ *
+ * Initializes the model and the graphical view and start the simulation (done
+ * by the model).
+ *
  * @author hm
  *
  */
 public class Simulator {
+    /**
+     * The main routine.
+     *
+     * @param args
+     *            the program arguments
+     */
     public static void main(String[] args) {
         Simulator simulator = new Simulator();
         simulator.exec();
     }
 
     /**
-     * Executes the simulation.
+     * Initializes the model and the graphical view.
      */
     public void exec() {
         Model model = new Model();
diff --git a/src/jlecture/swt/PanelSWT.java b/src/jlecture/swt/PanelSWT.java
index 332994e..ce2f30b 100644
--- a/src/jlecture/swt/PanelSWT.java
+++ b/src/jlecture/swt/PanelSWT.java
@@ -48,10 +48,10 @@ class PanelSWT extends JPanel {
     private void doDrawing(Graphics graphics) {
         Graphics2D g2d = (Graphics2D) graphics;
 
-        g2d.setColor(this.foreground);
-        g2d.setBackground(this.background);
+        g2d.setColor(foreground);
+        g2d.setBackground(background);
 
-        for (IWidget item : this.model.getItems()) {
+        for (IWidget item : model.getItems()) {
             Widget item2 = (Widget) item;
             item2.draw(g2d);
         }
diff --git a/src/jlecture/swt/RectangleSWT.java b/src/jlecture/swt/RectangleSWT.java
index 49d37b9..19bf6a7 100644
--- a/src/jlecture/swt/RectangleSWT.java
+++ b/src/jlecture/swt/RectangleSWT.java
@@ -13,6 +13,10 @@ import jlecture.simulation.PointRW;
 /**
  * Implements a rectangle with real world coordinates.
  *
+ * @Note: The rectangle has real world coordinates but it will be shown with
+ *        pixel coordinates. The translation is done internally (using the
+ *        model).
+ *
  * @author hm
  *
  */
@@ -45,21 +49,21 @@ public class RectangleSWT extends Widget {
 
     @Override
     protected void calculateContour() {
-        this.contour.x = this.center.x - this.dimension.width / 2;
-        this.contour.y = this.center.y - this.dimension.height / 2;
-        this.contour.width = this.dimension.width;
-        this.contour.height = this.dimension.height;
+        contour.x = center.x - dimension.width / 2;
+        contour.y = center.y - dimension.height / 2;
+        contour.width = dimension.width;
+        contour.height = dimension.height;
     }
 
     @Override
     public void draw(Graphics2D graphics) {
         calculateContour();
-        this.model.transform(this.contour, this.contourSWT);
-        if (this.filled)
-            graphics.fillRect(this.contourSWT.x, this.contourSWT.y,
-                this.contourSWT.width, this.contourSWT.height);
+        model.transform(contour, contourSWT);
+        if (filled)
+            graphics.fillRect(contourSWT.x, contourSWT.y,
+                contourSWT.width, contourSWT.height);
         else
-            graphics.drawRect(this.contourSWT.x, this.contourSWT.y,
-                this.contourSWT.width, this.contourSWT.height);
+            graphics.drawRect(contourSWT.x, contourSWT.y,
+                contourSWT.width, contourSWT.height);
     }
 }
diff --git a/src/jlecture/swt/SheetSWT.java b/src/jlecture/swt/SheetSWT.java
index 337ff14..b76fab6 100644
--- a/src/jlecture/swt/SheetSWT.java
+++ b/src/jlecture/swt/SheetSWT.java
@@ -14,16 +14,24 @@ import jlecture.simulation.IWidget;
 import jlecture.simulation.Model;
 import jlecture.simulation.PointRW;
 
+/**
+ * Defines a windows driven by SWT.
+ *
+ * This window contains a panel with the view of the simulated world.
+ *
+ * @Note: this class uses pixel coordinates: the maximum x is right, the maximum
+ *        y is at the bottom.
+ *
+ * @author hm
+ *
+ */
 public class SheetSWT extends JFrame implements ISheet, ActionListener {
-    /**
-     *
-     */
     private static final long serialVersionUID = 1L;
-    Point position = null;
-    Dimension dimension = null;
-    String title = null;
-    Model model;
-    Timer timer;
+    private Point position = null;
+    private Dimension dimension = null;
+    private String title = null;
+    private Model model;
+    private Timer timer;
 
     /**
      * Constructor.
@@ -41,8 +49,8 @@ public class SheetSWT extends JFrame implements ISheet, ActionListener {
         this.dimension = dimension;
         this.title = title;
         this.model = model;
-        this.timer = new Timer(100, this);
-        this.timer.setInitialDelay(2000);
+        timer = new Timer(100, this);
+        timer.setInitialDelay(2000);
         model.setSheet(this);
         initUI();
     }
@@ -51,7 +59,7 @@ public class SheetSWT extends JFrame implements ISheet, ActionListener {
     public void actionPerformed(ActionEvent e) {
         // if (e.getActionCommand().equals(""))
         {
-            this.model.onTimer();
+            model.onTimer();
             repaint();
         }
     }
@@ -73,18 +81,18 @@ public class SheetSWT extends JFrame implements ISheet, ActionListener {
      */
     private void initUI() {
 
-        setTitle(this.title);
+        setTitle(title);
         setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
 
-        add(new PanelSWT(this.model));
+        add(new PanelSWT(model));
 
-        setSize(this.dimension.width, this.dimension.height);
+        setSize(dimension.width, dimension.height);
 
-        if (this.position == null)
+        if (position == null)
             // build the window in the center:
             setLocationRelativeTo(null);
         else
-            setLocation(this.position);
-        this.timer.start();
+            setLocation(position);
+        timer.start();
     }
 }
diff --git a/src/jlecture/swt/Widget.java b/src/jlecture/swt/Widget.java
index 0c3bf18..5201112 100644
--- a/src/jlecture/swt/Widget.java
+++ b/src/jlecture/swt/Widget.java
@@ -11,7 +11,13 @@ import jlecture.simulation.PointRW;
 import jlecture.simulation.RectangleRW;
 
 /**
- * Base class of all 2 dimensional drawing items.
+ * Base class of all drawing items.
+ *
+ * The widget is characterized by the center: Though it is very simple to
+ * calculate the distance of two widgets: the distance of the two centers.
+ *
+ * Another important property is the contour: this is the smallest rectangle
+ * containing all parts of the widget.
  *
  * @author hm
  *
@@ -35,8 +41,8 @@ public abstract class Widget implements IWidget {
     /**
      * Constructor.
      *
-     * @param sheet
-     *            the drawing sheet
+     * @param center
+     *            the central position of the widget.
      */
     public Widget(PointRW center, Model model) {
         this.center = center;
@@ -62,7 +68,7 @@ public abstract class Widget implements IWidget {
      */
     @Override
     public PointRW getCenter() {
-        return this.center;
+        return center;
     }
 
     /**
@@ -72,7 +78,7 @@ public abstract class Widget implements IWidget {
      */
     @Override
     public RectangleRW getContour() {
-        return this.contour;
+        return contour;
     }
 
     /**
@@ -80,13 +86,9 @@ public abstract class Widget implements IWidget {
      */
     @Override
     public Model getModel() {
-        return this.model;
+        return model;
     }
 
-    /**
-     * @param center
-     *            the center to set
-     */
     @Override
     public void setCenter(PointRW center) {
         this.center.x = center.x;
diff --git a/src/jlecture/swt/XCross.java b/src/jlecture/swt/XCross.java
index 3931e6b..9a34943 100644
--- a/src/jlecture/swt/XCross.java
+++ b/src/jlecture/swt/XCross.java
@@ -13,7 +13,7 @@ import jlecture.simulation.RectangleRW;
 
 /**
  * Implements a cross similar to a 'X' for SWT. These are the diagonals of a
- * square.
+ * rectangle.
  *
  * @author hm
  *
@@ -47,21 +47,21 @@ public class XCross extends Widget {
      */
     @Override
     protected void calculateContour() {
-        this.contour.x = this.center.x - this.dimension.width / 2;
-        this.contour.y = this.center.y - this.dimension.height / 2;
-        this.contour.width = this.dimension.width;
-        this.contour.height = this.dimension.height;
+        contour.x = center.x - dimension.width / 2;
+        contour.y = center.y - dimension.height / 2;
+        contour.width = dimension.width;
+        contour.height = dimension.height;
     }
 
     @Override
     public void draw(Graphics2D graphics) {
         calculateContour();
-        this.model.transform(this.contour, this.contourSWT);
-        graphics.drawLine(this.contourSWT.x, this.contourSWT.y,
-            this.contourSWT.x + this.contourSWT.width, this.contourSWT.y
-            + this.contourSWT.height);
-        graphics.drawLine(this.contourSWT.x + this.contourSWT.width,
-            this.contourSWT.y, this.contourSWT.x, this.contourSWT.y
-            + this.contourSWT.height);
+        model.transform(contour, contourSWT);
+        graphics.drawLine(contourSWT.x, contourSWT.y,
+            contourSWT.x + contourSWT.width, contourSWT.y
+            + contourSWT.height);
+        graphics.drawLine(contourSWT.x + contourSWT.width,
+            contourSWT.y, contourSWT.x, contourSWT.y
+            + contourSWT.height);
     }
 }
-- 
2.39.5