From 3ac93ae1e5f8779bffded1e07473326aec42516c Mon Sep 17 00:00:00 2001
From: Fan-Wu Yang <fwy13@uclive.ac.nz>
Date: Thu, 9 Mar 2017 16:43:30 +1300
Subject: [PATCH] Documentation and Refactor - Changed Race to an abstract
 class - Protected and privated certain variables - Wrote Javadocs for the
 classes and functions - Moved generate race from RandomisedRace and
 ConstantVelocityRace to the abstract Race class - Added string checking
 exception for Scanner for whether to run in 1 minute or 5 minutes
 #pair[fwy13, cbt24]

---
 .idea/misc.xml                                | 18 +++++++++
 src/main/java/seng302/Boat.java               | 17 +++++++++
 .../java/seng302/ConstantVelocityRace.java    | 14 ++++++-
 src/main/java/seng302/Event.java              | 37 +++++++++++++++++++
 src/main/java/seng302/Race.java               | 32 ++++++++++++----
 src/main/java/seng302/RaceMarker.java         | 35 ++++++++++++++++--
 src/main/java/seng302/RandomisedRace.java     | 14 ++++++-
 7 files changed, 152 insertions(+), 15 deletions(-)

diff --git a/.idea/misc.xml b/.idea/misc.xml
index 3dd364d0..347c25ca 100644
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -1,5 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
+  <component name="JavadocGenerationManager">
+    <option name="OUTPUT_DIRECTORY" />
+    <option name="OPTION_SCOPE" value="protected" />
+    <option name="OPTION_HIERARCHY" value="true" />
+    <option name="OPTION_NAVIGATOR" value="true" />
+    <option name="OPTION_INDEX" value="true" />
+    <option name="OPTION_SEPARATE_INDEX" value="true" />
+    <option name="OPTION_DOCUMENT_TAG_USE" value="false" />
+    <option name="OPTION_DOCUMENT_TAG_AUTHOR" value="false" />
+    <option name="OPTION_DOCUMENT_TAG_VERSION" value="false" />
+    <option name="OPTION_DOCUMENT_TAG_DEPRECATED" value="true" />
+    <option name="OPTION_DEPRECATED_LIST" value="true" />
+    <option name="OTHER_OPTIONS" value="" />
+    <option name="HEAP_SIZE" />
+    <option name="LOCALE" />
+    <option name="OPEN_IN_BROWSER" value="true" />
+    <option name="OPTION_INCLUDE_LIBS" value="false" />
+  </component>
   <component name="MavenProjectsManager">
     <option name="originalFiles">
       <list>
diff --git a/src/main/java/seng302/Boat.java b/src/main/java/seng302/Boat.java
index 64c68e24..e926a188 100644
--- a/src/main/java/seng302/Boat.java
+++ b/src/main/java/seng302/Boat.java
@@ -9,19 +9,36 @@ public class Boat {
     private String name;
     private double velocity;
 
+    /**
+     * Boat initialiser which keeps all of the information of the boat.
+     * @param name Name of the Boat.
+     * @param velocity Speed in m/s that the boat travels at.
+     */
     public Boat(String name, double velocity){
         this.velocity = velocity;
         this.name = name;
     }
 
+    /**
+     *
+     * @return The name of the boat
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     *
+     * @return returns the speed of the boat.
+     */
     public double getVelocity() {
         return velocity;
     }
 
+    /**
+     *
+     * @return The Name of the boat.
+     */
     public String toString(){
         return getName();
     }
diff --git a/src/main/java/seng302/ConstantVelocityRace.java b/src/main/java/seng302/ConstantVelocityRace.java
index 1f4641af..b045d2a8 100644
--- a/src/main/java/seng302/ConstantVelocityRace.java
+++ b/src/main/java/seng302/ConstantVelocityRace.java
@@ -6,12 +6,22 @@ import java.util.Collections;
  * Created by cbt24 on 6/03/17.
  */
 public class ConstantVelocityRace extends Race {
+    /**
+     * Initialiser for a Race with constant velocity.
+     * @param boats array of boats
+     * @param marks array of RaceMarkers that the boats need to pass in order to finish the course.
+     * @param timescale integer that the race is at timescale = 1000ms
+     * @see seng302.Boat
+     * @see seng302.RaceMarker
+     */
     public ConstantVelocityRace(Boat[] boats, RaceMarker[] marks, int timescale) {
         super(boats, marks, timescale);
-        generateRace();
     }
 
-    private void generateRace() {
+    /**
+     * Generates the Race with respects to boat speed.
+     */
+    protected void generateRace() {
         for(Boat boat : boats) {
             for(int i = 0; i < marks.length; i++) {
                 RaceMarker raceMarker = marks[i];
diff --git a/src/main/java/seng302/Event.java b/src/main/java/seng302/Event.java
index 0cc72c05..d68dcea6 100644
--- a/src/main/java/seng302/Event.java
+++ b/src/main/java/seng302/Event.java
@@ -9,12 +9,29 @@ public class Event {
     private int time;
     private RaceMarker goalMarker;
 
+    /**
+     * Initaliser for Racemaker without a goal node (such as the Finish line).
+     * @param raceMarker current Racemarker that has just been passed.
+     * @param boat Boat that has been passed.
+     * @param time time in seconds that the event occurred.
+     * @see seng302.RaceMarker
+     * @see seng302.Boat
+     */
     public Event(RaceMarker raceMarker, Boat boat, int time){
         this.raceMarker = raceMarker;
         this.boat = boat;
         this.time = time;
     }
 
+    /**
+     * Initaliser for Racemaker with a goal node.
+     * @param raceMarker current Racemarker that has just been passed.
+     * @param boat Boat that has been passed.
+     * @param time time in seconds that the event occurred.
+     * @param goalMarker the next marker that the boat is aiming for.
+     * @see seng302.RaceMarker
+     * @see seng302.Boat
+     */
     public Event(RaceMarker raceMarker, Boat boat, int time, RaceMarker goalMarker){
         this.raceMarker = raceMarker;
         this.boat = boat;
@@ -22,24 +39,44 @@ public class Event {
         this.goalMarker = goalMarker;
     }
 
+    /**
+     * Calculates the bearing of the travel via map coordinates of the raceMarkers
+     * @return
+     */
     public double calculateHeading(){
         //to be changed to coordinates when used to match reality.
         double thetaHat = Math.atan2((goalMarker.getLatitude() - raceMarker.getLatitude()), (goalMarker.getLongitude() - raceMarker.getLongitude()));
         return thetaHat >= 0 ? Math.toDegrees(thetaHat): Math.toDegrees(thetaHat + 2 * Math.PI);
     }
 
+    /**
+     *
+     * @return the raceMarker that the boat has just passed.
+     */
     public RaceMarker getRaceMarker() {
         return raceMarker;
     }
 
+    /**
+     *
+     * @return the boat that this event occured for.
+     */
     public Boat getBoat() {
         return boat;
     }
 
+    /**
+     *
+     * @return the time the event occurred
+     */
     public int getTime(){
         return this.time;
     }
 
+    /**
+     *
+     * @return the event as a string in format {Boat Name} passed {RaceMarker Name} at {Time Event Occurred} seconds at heading {Heading}.
+     */
     public String toString() {
         String stringToReturn = boat.getName() + " passed " + raceMarker.toString() + " at " + time + " seconds";
         if (goalMarker != null){
diff --git a/src/main/java/seng302/Race.java b/src/main/java/seng302/Race.java
index 69656156..30195da8 100644
--- a/src/main/java/seng302/Race.java
+++ b/src/main/java/seng302/Race.java
@@ -4,23 +4,34 @@ package seng302;
 import java.util.*;
 
 /**
+ * Parent class for races
  * Created by fwy13 on 3/03/17.
  */
-public class Race {
-    Boat[] boats;
-    RaceMarker[] marks;
-    int timescale = 1000;
-
-    LinkedList<Event> events = new LinkedList<Event>();
-    Timer timer = new Timer();
+public abstract class Race {
+    protected Boat[] boats;
+    protected RaceMarker[] marks;
+    protected int timescale = 1000;
 
+    protected LinkedList<Event> events = new LinkedList<Event>();
+    protected Timer timer = new Timer();
 
+    /**
+     * Initailiser for Race
+     * @param boats Takes in an array of boats that are participating in the race.
+     * @param marks Number of marks in order that the boats pass in order to complete the race.
+     * @param timescale Number or milliseconds that = 1000ms.
+     */
     public Race(Boat[] boats, RaceMarker[] marks, int timescale) {
         this.boats = boats;
         this.marks = marks;
         this.timescale = timescale;
+        generateRace();
     }
 
+    /**
+     * Starts the Race Simulation, playing the race start to finish with the timescale.
+     * This prints the boats participating, the order that the events occur in time order, and the respective information of the events.
+     */
     public void simulateRace(){
         //show the boats participating.
         System.out.println("Boats Participating:");
@@ -62,4 +73,11 @@ public class Race {
         }, (events.getLast().getTime() + 1) * timescale);
     }
 
+    /**
+     * This function is a function that generates the Race and populates the events list.
+     * Is automatically called by the initialiser function, so that simulateRace() does not return an empty race.
+     * @see Race#simulateRace()
+     */
+    protected abstract void generateRace();
+
 }
diff --git a/src/main/java/seng302/RaceMarker.java b/src/main/java/seng302/RaceMarker.java
index 41c082ec..f38aeae4 100644
--- a/src/main/java/seng302/RaceMarker.java
+++ b/src/main/java/seng302/RaceMarker.java
@@ -4,11 +4,18 @@ package seng302;
  * Created by cbt24 on 6/03/17.
  */
 public class RaceMarker {
-    String name;
-    double distance;
-    double latitude;
-    double longitude;
+    private String name;
+    private double distance;
+    private double latitude;
+    private double longitude;
 
+    /**
+     * RaceMarker Initialiser
+     * @param name Name of the RaceMarker
+     * @param distance Total Distance located in the Race
+     * @param latitude Latitude of where it exists in the race (x coordinate)
+     * @param longitude Longitude of where it exists in the race (y coordinate)
+     */
     public RaceMarker(String name, double distance, double latitude, double longitude) {
         this.name = name;
         this.distance = distance;
@@ -16,22 +23,42 @@ public class RaceMarker {
         this.longitude = longitude;
     }
 
+    /**
+     *
+     * @return the name of the RaceMarker
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     *
+     * @return the total distance location in the race.
+     */
     public double getDistance() {
         return distance;
     }
 
+    /**
+     *
+     * @return the latitude that the RaceMarker exists at.
+     */
     public double getLatitude() {
         return latitude;
     }
 
+    /**
+     *
+     * @return the longitude that the RaceMarker exists at.
+     */
     public double getLongitude() {
         return longitude;
     }
 
+    /**
+     *
+     * @return the name of the RaceMarker
+     */
     public String toString() {
         return name;
     }
diff --git a/src/main/java/seng302/RandomisedRace.java b/src/main/java/seng302/RandomisedRace.java
index e675a2d9..08bfa6b0 100644
--- a/src/main/java/seng302/RandomisedRace.java
+++ b/src/main/java/seng302/RandomisedRace.java
@@ -7,12 +7,22 @@ import java.util.Random;
  * Created by cbt24 on 6/03/17.
  */
 public class RandomisedRace extends Race {
+    /**
+     * Randomise race, this is a race that the boats cross each mark randomly, and is a extension of Race.
+     * @param boats
+     * @param marks
+     * @param timescale
+     * @see seng302.Race
+     */
     public RandomisedRace(Boat[] boats, RaceMarker[] marks, int timescale) {
         super(boats, marks, timescale);
-        generateRace();
     }
 
-    private void generateRace() {
+    /**
+     * Generates the Race to be reported when Simulate Race in the Race class is called.
+     * @see Race#simulateRace()
+     */
+    protected void generateRace() {
         Random rand = new Random();
         for (Boat boat: this.boats){
             events.add(new Event(new RaceMarker("Start", 0, 0, 0), boat, 0));