Javadoc and commented RaceData class

#story[778]

mock/src/main/java/seng302/Data/RaceData.java

@@ -18,7 +18,6 @@ import javax.xml.transform.dom.DOMSource;
 import javax.xml.transform.stream.StreamResult;
 import java.io.StringWriter;
 import java.time.OffsetDateTime;
-import java.util.List;
 
 /**
  * Created by esa46 on 21/04/17.
@@ -26,9 +25,8 @@ import java.util.List;
 public class RaceData {
 
     private RaceDataSource dataSource;
-    Document doc;
-    Element raceElement;
-
+    private Document doc;
+    private Element rootElement;
     private OffsetDateTime creationTimeDate;
 
     public RaceData(RaceDataSource dataSource) {
@@ -36,17 +34,22 @@ public class RaceData {
         creationTimeDate = OffsetDateTime.now();
     }
 
+    /**
+     * Creates an AC35 officially formatted xml description of a race.
+     * @return String containing xml - formatted race description
+     */
     public String createXML() {
 
         try {
+
+            //create base xml document
             DocumentBuilderFactory docFactory = DocumentBuilderFactory.newInstance();
             DocumentBuilder docBuilder = docFactory.newDocumentBuilder();
             doc = docBuilder.newDocument();
 
-
-            //root element;
-            raceElement = doc.createElement("Race");
-            doc.appendChild(raceElement);
+            //create root element (In this case, "Race")
+            rootElement = doc.createElement("Race");
+            doc.appendChild(rootElement);
 
             appendChildElements();
 
@@ -69,6 +72,9 @@ public class RaceData {
         }
     }
 
+    /**
+     * Creates all necessary child elements and appends them to the xml doc
+     */
     private void appendChildElements() {
         appendRaceId();
         appendRaceType();
@@ -79,31 +85,46 @@ public class RaceData {
         appendCourseLimit();
     }
 
+    /**
+     * Creates and appends race id element
+     */
     private void appendRaceId() {
         Element raceIdElement = doc.createElement("RaceID");
         raceIdElement.appendChild(doc.createTextNode(dataSource.getRaceId()));
-        raceElement.appendChild(raceIdElement);
+        rootElement.appendChild(raceIdElement);
     }
 
+    /**
+     * Creates and appends race type element
+     */
     private void appendRaceType() {
         Element raceTypeElement = doc.createElement("RaceType");
         raceTypeElement.appendChild(doc.createTextNode(dataSource.getRaceType()));
-        raceElement.appendChild(raceTypeElement);
+        rootElement.appendChild(raceTypeElement);
     }
 
+    /**
+     * Creates and appends creation time date element
+     */
     private void appendCreationTimeDate() {
         Element creationTimeElement = doc.createElement("CreationTimeDate");
         creationTimeElement.appendChild(doc.createTextNode(creationTimeDate.toString()));
-        raceElement.appendChild(creationTimeElement);
+        rootElement.appendChild(creationTimeElement);
     }
 
+    /**
+     * Creates and appends race start time element, which is 3 minutes after the race was created by default
+     */
     private void appendRaceStartTime() {
         Element startTimeElement = doc.createElement("RaceStartTime");
         startTimeElement.setAttribute("Time", (creationTimeDate.plusMinutes(3)).toString());
         startTimeElement.setAttribute("Postpone", "false");
-        raceElement.appendChild(startTimeElement);
+        rootElement.appendChild(startTimeElement);
     }
 
+    /**
+     * Creates and appends participants element
+     */
     private void appendParticipants() {
         Element participantsElement = doc.createElement("Participants");
 
@@ -112,9 +133,12 @@ public class RaceData {
             yachtElement.setAttribute("SourceID", boat.getSourceID() + "");
             participantsElement.appendChild(yachtElement);
         }
-        raceElement.appendChild(participantsElement);
+        rootElement.appendChild(participantsElement);
     }
 
+    /**
+     * Creates and appends course elements
+     */
     private void appendCourse() {
         Element courseElement = doc.createElement("Course");
         Element compoundMarkSeqElement = doc.createElement("CompoundMarkSequence");
@@ -127,11 +151,16 @@ public class RaceData {
             i++;
         }
 
-        raceElement.appendChild(compoundMarkSeqElement);
-        raceElement.appendChild(courseElement);
+        rootElement.appendChild(compoundMarkSeqElement);
+        rootElement.appendChild(courseElement);
     }
 
 
+    /**
+     * Creates a mark element for insertion in a coumpound mark element
+     * @param marker GPS coordinates of the mark
+     * @return Element mark element
+     */
     private Element createMark(GPSCoordinate marker) {
         Element mark = doc.createElement("Mark");
         mark.setAttribute("TargetLat", marker.getLatitude() + "");
@@ -139,6 +168,12 @@ public class RaceData {
         return mark;
     }
 
+    /**
+     * Creates a compound marker holding one or two marks,and a sequence number
+     * @param marker marker
+     * @param i sequence number
+     * @return Element compound mark element
+     */
     private Element createCompoundMarker(Marker marker, int i) {
         Element compoundMarkElement = doc.createElement("CompoundMark");
         compoundMarkElement.setAttribute("CompoundMarkId", i + "");
@@ -153,6 +188,11 @@ public class RaceData {
         return compoundMarkElement;
     }
 
+    /**
+     * Creates a corner element
+     * @param i sequence number
+     * @return Element corner element
+     */
     private Element createCornerElement(int i) {
         Element cornerElement = doc.createElement("Corner");
         cornerElement.setAttribute("SeqID", i + "");
@@ -161,6 +201,9 @@ public class RaceData {
         return cornerElement;
     }
 
+    /**
+     * Creates and appends course limits element (boundaries)
+     */
     private void appendCourseLimit() {
         int j = 1;
 
@@ -168,7 +211,6 @@ public class RaceData {
         for (GPSCoordinate coordinate : dataSource.getBoundary()) {
             Element limitElement = doc.createElement("Limit");
             limitElement.setAttribute("SeqID", j + "");
-
             limitElement.setAttribute("Lat", coordinate.getLatitude() + "");
             limitElement.setAttribute("Lon", coordinate.getLongitude() + "");
 
@@ -177,7 +219,7 @@ public class RaceData {
             j++;
         }
 
-        raceElement.appendChild(courseLimitElement);
+        rootElement.appendChild(courseLimitElement);
     }