Merge pull request #32 from battlecode/javadocs

Add javadocs and bytecode costs

Author: j-mao

build.gradle

@@ -272,13 +272,6 @@ task releaseClientLinux32(type: Zip, dependsOn: ['prodClient']) {
 
 
 
-task updateVersion() {
-  // new File("frontend/public/version.txt").write(project.findProperty('release_version'))
-}
-
-
-
-publish.dependsOn(updateVersion)
 publishing {
   repositories {
     maven {
@@ -296,11 +289,10 @@ publishing {
   publications {
     server(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21'
+      artifactId 'battlecode22'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact release_main
-    
 
       artifact release_docs {
         classifier 'javadoc'
@@ -312,39 +304,39 @@ publishing {
 
     clientWin(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21-client-win'
+      artifactId 'battlecode22-client-win'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact releaseClientWin
     }
 
     clientMac(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21-client-mac'
+      artifactId 'battlecode22-client-mac'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact releaseClientMac
     }
 
     clientLinux(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21-client-linux'
+      artifactId 'battlecode22-client-linux'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact releaseClientLinux
     }
 
     clientWin32(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21-client-win-32'
+      artifactId 'battlecode22-client-win-32'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact releaseClientWin32
     }
 
     clientLinux32(MavenPublication) {
       groupId 'org.battlecode'
-      artifactId 'battlecode21-client-linux-32'
+      artifactId 'battlecode22-client-linux-32'
       version project.findProperty('release_version') ?: 'NONSENSE'
 
       artifact releaseClientLinux32

engine/src/main/battlecode/common/AnomalyScheduleEntry.java

@@ -1,30 +1,67 @@
 package battlecode.common;
 
+/**
+ * AnomalyScheduleEntry describes a single Anomaly in the Anomaly schedule. The
+ * schedule of Anomalies is predetermined for each map, and you can retrieve it
+ * by calling {@link RobotController#getAnomalySchedule}. Each schedule entry
+ * provides information about the round on which it occurs, and the type of the
+ * Anomaly.
+ * <P>
+ * Note that the Singularity is not included in the schedule. You should instead
+ * check {@link GameConstants#GAME_MAX_NUMBER_OF_ROUNDS}.
+ */
 public class AnomalyScheduleEntry {
-
+    /**
+     * The round on which this Anomaly will occur. The Anomaly will occur at the
+     * end of this round, that is, after all robots have taken their turn.
+     */
     public final int roundNumber;
+
+    /**
+     * The type of this Anomaly.
+     */
     public final AnomalyType anomalyType;
 
-    public AnomalyScheduleEntry(int round, AnomalyType anomaly) {
+    /**
+     * Constructs an AnomalyScheduleEntry using the given round number and
+     * Anomaly type. Note that this does not actually insert the Anomaly into
+     * the schedule, but only creates a local object that you are free to
+     * manipulate. The global Anomaly schedule is fixed and cannot be changed;
+     * to envision an Anomaly with a Sage, see {@link RobotController#envision}.
+     *
+     * @param round the round number of the Anomaly
+     * @param type the type of the Anomaly
+     */
+    public AnomalyScheduleEntry(int round, AnomalyType type) {
         this.roundNumber = round;
-        this.anomalyType = anomaly;
+        this.anomalyType = type;
     }
 
     /**
-     * @return a copy of the entry
+     * Constructs a copy of this schedule entry. Note that this does not
+     * actually cause the Anomaly to happen twice, but only creates a local
+     * object that you are free to manipulate. The global Anomaly schedule is
+     * fixed and cannot be changed; to envision an Anomaly with a Sage, see
+     * {@link RobotController#envision}.
+     *
+     * @return a copy of this AnomalyScheduleEntry
      */
     public AnomalyScheduleEntry copyEntry() {
         return new AnomalyScheduleEntry(this.roundNumber, this.anomalyType);
     }
 
     /**
-     * Returns whether two AnomalyScheduleEntrys are equal.
+     * Returns whether two AnomalyScheduleEntry objects are equivalent.
+     *
+     * @param other the AnomalyScheduleEntry to compare with
+     * @return whether the two AnomalyScheduleEntry objects are equivalent
      *
-     * @param other the other anomaly schedule entry to compare to
-     * @return whether the two anomaly schedules entry are equivalent
+     * @battlecode.doc.costlymethod
      */
-    public boolean equals(AnomalyScheduleEntry other) {
-        if (this.roundNumber != other.roundNumber) return false;
-        return this.anomalyType == other.anomalyType;
+    @Override
+    public boolean equals(Object other) {
+        if (other == null || getClass() != other.getClass()) return false;
+        AnomalyScheduleEntry casted = (AnomalyScheduleEntry) other;
+        return this.roundNumber == casted.roundNumber && this.anomalyType == casted.anomalyType;
     }
 }

engine/src/main/battlecode/common/AnomalyType.java

@@ -1,17 +1,74 @@
 package battlecode.common;
 
 /**
- * Holds the different anomalies in the game.
+ * AnomalyType represents the type of a scheduled or envisioned Anomaly. You
+ * can access the type of scheduled Anomalies from
+ * {@link AnomalyScheduleEntry#anomalyType}, and envision your own Anomalies with
+ * Sages by using {@link RobotController#envision}.
+ * <P>
+ * AnomalyType also provides information about the strenghts of each Anomaly, as
+ * well as other properties.
+ * <P>
+ * Note that the Singularity is not included in the schedule. You should instead
+ * check {@link GameConstants#GAME_MAX_NUMBER_OF_ROUNDS}.
  */
 public enum AnomalyType {
+    /**
+     * Abyss causes proportional amounts of metal resources to be lost. When
+     * global, the entire map as well as team reserves are affected. When
+     * envisioned, a local region of the map is affected.
+     * <P>
+     * {@link #globalPercentage} and {@link #sagePercentage} specify the
+     * proportion of metals lost.
+     */
     ABYSS       (true,    true,   0.1f,    0.2f),
+
+    /**
+     * Charge deals concentrated damage to Droids. When global, the top
+     * {@link #globalPercentage} Droids with the most nearby friendly units are
+     * destroyed. When envisioned, all nearby enemy Droids lose
+     * {@link #sagePercentage} of their maximum health.
+     */
     CHARGE      (true,    true,   0.05f,   0.1f),
+
+    /**
+     * Fury deals concentrated proportional damage to Turrets. When global, all
+     * Turrets are affected. When envisioned, a local region is affected.
+     * <P>
+     * {@link #globalPercentage} and {@link #sagePercentage} specify the
+     * amount of damage dealt, as a proportion of the Turret's maximum health.
+     */
     FURY        (true,    true,   0.05f,   0.1f),
+
+    /**
+     * Vortex upends the world by transforming the map terrain. It can only
+     * occur globally.
+     * <P>
+     * The values of {@link #globalPercentage} and {@link #sagePercentage} are
+     * unused.
+     */
     VORTEX      (true,    false,  0,      0);
-    
+
+    /**
+     * Whether this type of Anomaly could appear in the global schedule.
+     */
     public final boolean isGlobalAnomaly;
+
+    /**
+     * Whether this type of Anomaly could be envisioned by Sages.
+     */
     public final boolean isSageAnomaly;
+
+    /**
+     * The strength of this Anomaly when globally scheduled. The precise
+     * definition of this value depends on the Anomaly type.
+     */
     public final float globalPercentage;
+
+    /**
+     * The strength of this Anomaly when envisioned by a Sage. The precise
+     * definition of this value depends on the Anomaly type.
+     */
     public final float sagePercentage;
 
     AnomalyType(boolean isGlobalAnomaly, boolean isSageAnomaly, float globalPercentage, float sagePercentage) {
@@ -20,4 +77,4 @@ public enum AnomalyType {
         this.globalPercentage    = globalPercentage;
         this.sagePercentage      = sagePercentage;
     }
-}
+}

engine/src/main/battlecode/common/BodyInfo.java

@@ -3,15 +3,14 @@
 import battlecode.instrumenter.inject.RobotMonitor;
 
 /**
- * Clock is a singleton that allows contestants to introspect the state of their running
- * code.
+ * Clock is a singleton that allows contestants to introspect the state of their
+ * running code.
  *
  * @author james
  */
 @SuppressWarnings("unused")
 public final class Clock {
-
-    /**
+    /*
      * IMPORTANT NOTE!
      * This class is reloaded for every individual robot.
      * See Loader for more information.
@@ -28,20 +27,20 @@ public static void yield() {
 
     /**
      * Returns the number of bytecodes this robot has left in this round.
-     * @return the number of bytecodes this robot has left in this round.
      *
+     * @return the number of bytecodes this robot has left in this round
      * @battlecode.doc.costlymethod
      */
     public static int getBytecodesLeft() {
         return RobotMonitor.getBytecodesLeft();
     }
 
     /**
-     * Returns the number of bytecodes the current robot has executed since the beginning
-     *      of the current round.
-     * @return the number of bytecodes the current robot has executed since the beginning
-     *      of the current round.
+     * Returns the number of bytecodes the current robot has executed since the
+     * beginning of the current round.
      *
+     * @return the number of bytecodes the current robot has executed since the
+     *         beginning of the current round
      * @battlecode.doc.costlymethod
      */
     public static int getBytecodeNum() {

engine/src/main/battlecode/common/Clock.java

@@ -50,9 +50,14 @@ public enum Direction {
     CENTER(0, 0);
 
     /**
-     * Change in x, change in y.
+     * Change in x.
      */
-    public final int dx, dy;
+    public final int dx;
+
+    /**
+     * Change in y.
+     */
+    public final int dy;
 
     Direction(int dx, int dy) {
         this.dx = dx;
@@ -102,9 +107,9 @@ public Direction rotateRight() {
 
     /**
      * Returns a list of all directions. This is equivalent to calling
-     * Direction.values().
+     * {@link Direction#values}.
      *
-     * @return array of all directions.
+     * @return array of all directions
      */
     public static Direction[] allDirections() {
         return Direction.values();
@@ -113,7 +118,7 @@ public static Direction[] allDirections() {
     /**
      * Returns a list of all cardinal directions.
      *
-     * @return array of all cardinal directions.
+     * @return array of all cardinal directions
      */
     public static Direction[] cardinalDirections() {
         return new Direction[]{Direction.NORTH, Direction.EAST, Direction.SOUTH, Direction.WEST};
@@ -122,7 +127,7 @@ public static Direction[] cardinalDirections() {
     /**
      * Returns the delta X of the direction.
      *
-     * @return the delta X of the direction.
+     * @return the delta X of the direction
      */
     public int getDeltaX() {
         return this.dx;
@@ -131,9 +136,9 @@ public int getDeltaX() {
     /**
      * Returns the delta Y of the direction.
      *
-     * @return the delta Y of the direction.
+     * @return the delta Y of the direction
      */
     public int getDeltaY() {
         return this.dy;
     }
-}
+}

engine/src/main/battlecode/common/Direction.java

@@ -35,7 +35,7 @@ public GameActionException(GameActionExceptionType type, String message) {
      * Gives the type of gameworld interaction that caused this GameActionException, which
      * was specified when this instance was constructed.
      *
-     * @return this GameActionException's type.
+     * @return this GameActionException's type
      */
     public GameActionExceptionType getType() {
         return type;