Added doc strings to RaceXML Creator #story[1096]

racevisionGame/src/main/java/mock/xml/RaceXMLCreator.java

@@ -15,10 +15,17 @@ import javax.xml.bind.Marshaller;
 import java.io.StringWriter;
 
 /**
- * Created by Gondr on 3/08/2017.
+ * Helper Class for creating a Race XML
  */
 public class RaceXMLCreator {
 
+    /**
+     * Copy the race to a mock.xml.Race class from a RaceXMlReader
+     * @param reader RaceXMlReader
+     * @return string of the new mock.xml.Race
+     * @throws InvalidRaceDataException If the reader is unable to be read
+     * @throws XMLReaderException If the reader is unable to be read
+     */
     public static Race copyRace(RaceXMLReader reader) throws InvalidRaceDataException, XMLReaderException {
         RaceFactory raceFactory = new RaceFactory();
         Race race = raceFactory.createRace();
@@ -80,6 +87,12 @@ public class RaceXMLCreator {
         return race;
     }
 
+    /**
+     * Sets a mock.xml.Mark from a shared.model.Mark
+     * @param raceFactory race Factory for creating mock.xml.Race classes and subclasses
+     * @param mark Mark to be converted.
+     * @return converted mock.xml.Mark.
+     */
     public static Race.Course.CompoundMark.Mark setMarkFromMark(RaceFactory raceFactory, Mark mark){
         if (mark != null) {
             Race.Course.CompoundMark.Mark m = raceFactory.createRaceCourseCompoundMarkMark();
@@ -92,6 +105,11 @@ public class RaceXMLCreator {
         return null;
     }
 
+    /**
+     * get the windward gate in a race
+     * @param reader reads in the mark
+     * @return the windward gate.
+     */
     public static CompoundMark getWindwardGate(RaceXMLReader reader){
         for (CompoundMark mark: reader.getCompoundMarks()){
             if (mark.getName().equals("Windward Gate")) return mark;
@@ -99,6 +117,11 @@ public class RaceXMLCreator {
         return null;
     }
 
+    /**
+     * get the leeward gate in a race
+     * @param reader reads in the mark
+     * @return the leeward gate.
+     */
     public static CompoundMark getLeewardGate(RaceXMLReader reader){
         for (CompoundMark mark: reader.getCompoundMarks()){
             if (mark.getName().equals("Leeward Gate")) return mark;
@@ -106,6 +129,15 @@ public class RaceXMLCreator {
         return null;
     }
 
+    /**
+     * Rotates the race in a specified direction.
+     * @param s xml file name
+     * @param degrees degrees to rotate
+     * @return the new xml file as a string
+     * @throws XMLReaderException if the xml is not readable
+     * @throws InvalidRaceDataException if the race is invalid
+     * @throws JAXBException if the Race class cannot be parsed into a xml.
+     */
     public static String alterRaceToWind(String s, double degrees) throws XMLReaderException, InvalidRaceDataException, JAXBException {
         RaceXMLReader reader = new RaceXMLReader(s, XMLFileType.ResourcePath);
 
@@ -127,6 +159,11 @@ public class RaceXMLCreator {
         return sw.toString();
     }
 
+    /**
+     * Rotate the features in a race such as the boundary, and the marks.
+     * @param race the race to alter
+     * @param degrees the degrees to rotate by.
+     */
     public static void alterRaceRotation(Race race, double degrees){
         GPSCoordinate center = getCenter(race);
         for(Race.CourseLimit.Limit limit: race.getCourseLimit().getLimit()){
@@ -145,10 +182,22 @@ public class RaceXMLCreator {
         }
     }
 
+    /**
+     * Converts a Race.CourseLimit.Limit to a GPS coordinate
+     * @param limit limit to convert
+     * @return gps coordinate corresponding to the limit
+     */
     public static GPSCoordinate limitToGPSCoordinate(Race.CourseLimit.Limit limit){
         return new GPSCoordinate(Double.parseDouble(limit.getLat()), Double.parseDouble(limit.getLon()));
     }
 
+    /**
+     * get new gps coordinate after rotating
+     * @param pivot center point to rotating from.
+     * @param point point to rotate
+     * @param degrees number of degress to rotate by
+     * @return the new GPSCoordinate of the transformed point.
+     */
     public static GPSCoordinate rotate(GPSCoordinate pivot, GPSCoordinate point, double degrees){
         double radDeg = Math.toRadians(degrees);
         double deltaLat = (point.getLatitude() - pivot.getLatitude());
@@ -159,10 +208,20 @@ public class RaceXMLCreator {
         return new GPSCoordinate(resLat, resLon);
     }
 
+    /**
+     * obtains the GPSCoordinates of a mark
+     * @param mark mark to obtain the GPSCoordinates of
+     * @return the GPSCOordinatess of a mark
+     */
     public static GPSCoordinate markToGPSCoordinate(Race.Course.CompoundMark.Mark mark){
         return new GPSCoordinate(Double.parseDouble(mark.getTargetLat()), Double.parseDouble(mark.getTargetLng()));
     }
 
+    /**
+     * get the center of a race
+     * @param race race to get the center of
+     * @return GPSCoordinates of the center
+     */
     public static GPSCoordinate getCenter(Race race){
         double avgLat = 0;
         double avgLng = 0;
@@ -174,6 +233,13 @@ public class RaceXMLCreator {
         avgLng = avgLng/race.getCourseLimit().getLimit().size();
         return new GPSCoordinate(avgLat, avgLng);
     }
+
+    /**
+     * gets the angle of a line
+     * @param coord1 point a of the line
+     * @param coord2 point b of the line
+     * @return the angle in degrees that the bearing of the line is [-180, 180]
+     */
     public static double getLineAngle(GPSCoordinate coord1, GPSCoordinate coord2){
         double dx = coord1.getLongitude() - coord2.getLongitude();
         double dy = coord1.getLatitude() - coord2.getLatitude();